API Changelog Bot c551a76ced changelog: 522a737 - feat: Knife4j网关文档修复 + AI Bridge增强 + bootstrap默认Nacos改本地

2026-03-16 16:50:37 +08:00

1.8 MiB

原始文件 Blame 文件历史

接口变更记录

提交信息

项目	内容
Hash	`522a737928b06cb5114e815e08b7ee997075ce6d`
作者	wx
时间	2026-03-16 16:50:04 +0800
说明	feat: Knife4j网关文档修复 + AI Bridge增强 + bootstrap默认Nacos改本地

变更文件总览

A	design-01-mengma-detail.jpg
A	design-mengma-100pct.jpg
A	design-mengma-detail.jpg
M	docs/CLAUDE_WORKFLOW/CODE_STANDARDS.md
M	docs/CLAUDE_WORKFLOW/architect/GUIDE.md
M	docs/CLAUDE_WORKFLOW/qa/GUIDE.md
M	docs/CLAUDE_WORKFLOW/reviewer/GUIDE.md
M	docs/CLAUDE_WORKFLOW/senior-dev/GUIDE.md
M	hl-callback-service/src/main/java/com/hulalv/callback/config/Knife4jConfig.java
M	hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java
M	hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java
M	hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClient.java
M	hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClientFallback.java
M	hl-callback-service/src/main/java/com/hulalv/callback/handler/ApprovalEventHandler.java
M	hl-callback-service/src/main/java/com/hulalv/callback/handler/ContactChangeHandler.java
M	hl-callback-service/src/main/java/com/hulalv/callback/handler/ExternalContactHandler.java
M	hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/InternalChatMessageController.java
M	hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/MsgAuditController.java
M	hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java
M	hl-callback-service/src/main/resources/bootstrap.yml
M	hl-common/src/main/java/com/hulalv/common/dto/AdminBasicDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/DepartmentDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/ExternalContactEventDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/FileBindRefsDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/FileUnbindRefsDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/OrderPayInfoDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/PaymentResultDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/RefundResultDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/ResourceDetailDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/TravelerValidationDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/WechatDeptSyncDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/WechatMessageDTO.java
M	hl-common/src/main/java/com/hulalv/common/dto/WechatUserSyncDTO.java
M	hl-common/src/main/java/com/hulalv/common/feign/MonitorFeignClient.java
M	hl-common/src/main/java/com/hulalv/common/feign/MonitorFeignFallbackFactory.java
M	hl-common/src/main/java/com/hulalv/common/feign/OrderRefundFeignClient.java
M	hl-common/src/main/java/com/hulalv/common/feign/OrderRefundFeignFallbackFactory.java
M	hl-common/src/main/java/com/hulalv/common/feign/ProductApprovalFeignClient.java
M	hl-common/src/main/java/com/hulalv/common/feign/ProductApprovalFeignFallbackFactory.java
M	hl-common/src/main/java/com/hulalv/common/feign/ResourceApprovalFeignClient.java
M	hl-common/src/main/java/com/hulalv/common/feign/ResourceApprovalFeignFallbackFactory.java
M	hl-common/src/main/java/com/hulalv/common/weather/AmapWeatherClient.java
M	hl-contract-service/src/main/java/com/hulalv/contract/config/Knife4jConfig.java
M	hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java
M	hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java
M	hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java
M	hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java
M	hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java
M	hl-contract-service/src/main/resources/bootstrap.yml
M	hl-file-service/src/main/java/com/hulalv/file/config/Knife4jConfig.java
M	hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java
M	hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java
M	hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java
M	hl-file-service/src/main/resources/bootstrap.yml
A	hl-gateway/src/main/java/com/hulalv/gateway/config/WebResourceConfig.java
M	hl-gateway/src/main/resources/bootstrap.yml
M	hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java
M	hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java
M	hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java
M	hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java
M	hl-guide-service/src/main/resources/bootstrap.yml
M	hl-insurance-service/src/main/java/com/hulalv/insurance/config/Knife4jConfig.java
M	hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java
M	hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java
M	hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java
M	hl-insurance-service/src/main/resources/bootstrap.yml
M	hl-material-service/src/main/java/com/hulalv/material/config/Knife4jConfig.java
M	hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java
M	hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java
M	hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java
M	hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java
M	hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java
M	hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java
M	hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java
M	hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java
M	hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java
M	hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java
M	hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java
M	hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java
M	hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java
M	hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java
M	hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java
M	hl-material-service/src/main/resources/bootstrap.yml
M	hl-monitor-service/src/main/java/com/hulalv/monitor/config/Knife4jConfig.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java
M	hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java
M	hl-monitor-service/src/main/resources/bootstrap.yml
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignClient.java
M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignFallbackFactory.java
M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignClient.java
M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignFallbackFactory.java
M	hl-mp-service/src/main/resources/bootstrap.yml
M	hl-order-service/src/main/java/com/hulalv/order/config/Knife4jConfig.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/service/WeatherService.java
M	hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java
M	hl-order-service/src/main/resources/bootstrap.yml
M	hl-payment-service/src/main/java/com/hulalv/payment/config/Knife4jConfig.java
M	hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java
M	hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java
M	hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java
M	hl-payment-service/src/main/resources/bootstrap.yml
M	hl-product-service/src/main/java/com/hulalv/product/config/Knife4jConfig.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java
M	hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java
M	hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java
M	hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java
M	hl-product-service/src/main/resources/bootstrap.yml
M	hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/config/Knife4jConfig.java
M	hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java
M	hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java
M	hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java
M	hl-resource-service/src/main/resources/bootstrap.yml
M	hl-review-service/src/main/java/com/hulalv/review/config/Knife4jConfig.java
M	hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java
M	hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java
M	hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java
M	hl-review-service/src/main/resources/bootstrap.yml
M	hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java
M	hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java
M	hl-task-service/src/main/resources/bootstrap.yml
M	hl-user-service/src/main/java/com/hulalv/user/config/Knife4jConfig.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java
M	hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java
M	hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java
M	hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java
M	hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java
M	hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java
M	hl-user-service/src/main/java/com/hulalv/user/service/SysJobService.java
M	hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java
M	hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java
M	hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java
A	hl-user-service/src/main/java/com/hulalv/user/vo/SysJobLogVO.java
A	hl-user-service/src/main/java/com/hulalv/user/vo/SysJobVO.java
M	hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java
M	hl-user-service/src/main/resources/bootstrap.yml
M	hl-user-service/src/test/java/com/hulalv/user/service/SysJobServiceTest.java
A	mastergo-overview.jpg
A	scripts/ai-bridge/ai_bridge.py
A	scripts/ai-bridge/ai_bridge.service
A	scripts/ai-bridge/mg-mengma-detail.jpg
A	scripts/ai-bridge/mg-preview.jpg
A	scripts/ai-bridge/setup.sh
A	scripts/ai-bridge/state.json
A	scripts/api-changelog-sync.sh
A	sql/add_customer_service_role.sql
M	sql/dict_data_seed.sql
A	sql/dict_fix_frontend.sql

Controller 接口变更

`hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java` (M)

接口变更 diff：

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java b/hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java
index a9d6ea9..adf49be 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java
@@ -21,7 +21,7 @@ import java.util.concurrent.Executors;
  * 路径: /callback/msg-audit
  */
 @Slf4j
-@Api(tags = "【回调接口】会话内容存档")
+@Api(tags = "【回调接口】会话内容存档", hidden = true)
 @RestController
 @RequestMapping("/callback")
 public class MsgAuditCallbackController {
@@ -59,7 +59,8 @@ public class MsgAuditCallbackController {
      * URL 验证端点。
      * 企业微信配置回调 URL 时发送 GET 请求验证，需解密 echostr 并返回明文。
      */
-    @ApiOperation("会话内容存档回调URL验证")
+    @ApiOperation(value = "会话内容存档回调URL验证",
+            notes = "企业微信会话内容存档的回调URL验证端点。使用独立的Token/AESKey，在企微后台配置会话存档回调URL时进行验证。")
     @GetMapping(value = "/msg-audit", produces = MediaType.TEXT_PLAIN_VALUE)
     public String verifyUrl(
             @RequestParam("msg_signature") String msgSignature,
@@ -89,7 +90,8 @@ public class MsgAuditCallbackController {
      * 企业微信在有新的存档消息时 POST 加密 XML 事件通知。
      * 通知仅表示"有新消息可拉取"，具体消息内容需通过 API 主动拉取。
      */
-    @ApiOperation("接收会话内容存档事件通知")
+    @ApiOperation(value = "接收会话内容存档事件通知",
+            notes = "企业微信在有新的存档消息时推送事件通知到此端点。通知仅表示'有新消息可拉取'，收到后异步触发消息拉取任务（通过Finance SDK API主动拉取具体内容并存储）。必须5秒内返回'success'。")
     @PostMapping(value = "/msg-audit",
             consumes = {MediaType.TEXT_XML_VALUE, MediaType.APPLICATION_XML_VALUE},
             produces = MediaType.TEXT_PLAIN_VALUE)

`hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java` (M)

接口变更 diff：

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java b/hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java
index cad043a..0b1d68b 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java
@@ -27,7 +27,7 @@ import java.io.StringReader;
  * No JWT auth required - uses WeChat's own signature verification.
  */
 @Slf4j
-@Api(tags = "【回调接口】企业微信回调")
+@Api(tags = "【回调接口】企业微信回调", hidden = true)
 @RestController
 @RequestMapping("/wx/callback")
 public class WxCallbackController {
@@ -88,7 +88,8 @@ public class WxCallbackController {
      * WeChat sends GET request to verify the callback URL.
      * Must decrypt echostr and return it as plain text.
      */
-    @ApiOperation("Callback URL verification")
+    @ApiOperation(value = "回调URL验证",
+            notes = "企业微信自建应用的回调URL验证端点。企微在配置回调URL时发送GET请求，需解密echostr并返回明文以完成验证。无需JWT认证，使用企微自有的签名校验机制。")
     @GetMapping(value = "/app", produces = MediaType.TEXT_PLAIN_VALUE)
     public String verifyUrl(
             @RequestParam("msg_signature") String msgSignature,
@@ -118,7 +119,8 @@ public class WxCallbackController {
      * WeChat POSTs encrypted XML for all event types.
      * We decrypt, parse, dispatch to handler, and return "success".
      */
-    @ApiOperation("Receive callback events")
+    @ApiOperation(value = "接收回调事件",
+            notes = "企业微信自建应用的事件接收端点。接收加密XML格式的事件通知（审批变更、消息等），解密后按事件类型分发：change_contact→通讯录变更，change_external_contact→外部联系人变更，open_approval_change→审批状态变更。必须5秒内返回'success'。")
     @PostMapping(value = "/app",
             consumes = {MediaType.TEXT_XML_VALUE, MediaType.APPLICATION_XML_VALUE},
             produces = MediaType.TEXT_PLAIN_VALUE)
@@ -162,7 +164,8 @@ public class WxCallbackController {
     // Contact Sync Callback Endpoints
     // ==========================================
 
-    @ApiOperation("Contact sync URL verification")
+    @ApiOperation(value = "联系人同步URL验证",
+            notes = "企业微信通讯录同步的回调URL验证端点。使用独立的Token/AESKey（与应用回调不同），用于接收通讯录变更事件的回调URL配置验证。")
     @GetMapping(value = "/contacts", produces = MediaType.TEXT_PLAIN_VALUE)
     public String verifyContactsUrl(
             @RequestParam("msg_signature") String msgSignature,
@@ -187,7 +190,8 @@ public class WxCallbackController {
         return result;
     }
 
-    @ApiOperation("Receive contact sync events")
+    @ApiOperation(value = "接收联系人同步事件",
+            notes = "企业微信通讯录变更事件接收端点。接收员工创建/更新/删除、部门变更等事件，解密后转发给ContactChangeHandler处理，同步更新本地管理员数据。必须5秒内返回'success'。")
     @PostMapping(value = "/contacts",
             consumes = {MediaType.TEXT_XML_VALUE, MediaType.APPLICATION_XML_VALUE},
             produces = MediaType.TEXT_PLAIN_VALUE)

`hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java` (M)

接口变更 diff：

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java b/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java
index f955c57..91ac6ed 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java
@@ -21,31 +21,33 @@ public class AdminClauseTemplateController {
 
     private final ClauseTemplateService clauseTemplateService;
 
-    @ApiOperation("获取启用的补充约定模板列表（创建合同用）")
+    @ApiOperation(value = "获取启用的补充约定模板列表（创建合同用）",
+            notes = "返回所有启用状态的补充约定模板，创建合同时选择需要附加的补充约定条款。\n\n**权限**：需管理员登录。")
     @GetMapping("/list")
     public Result<List<ClauseTemplateVO>> listActive() {
         return Result.success(clauseTemplateService.listActive());
     }
 
-    @ApiOperation("获取全部补充约定模板（管理页用）")
+    @ApiOperation(value = "获取全部补充约定模板（管理页用）", notes = "**关联字典**：\n- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用）")
     @GetMapping("/list-all")
     public Result<List<ClauseTemplateVO>> listAll() {
         return Result.success(clauseTemplateService.listAll());
     }
 
-    @ApiOperation("切换模板启用/停用状态")
+    @ApiOperation(value = "切换模板启用/停用状态", notes = "**关联字典**：\n- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用）")
     @PutMapping("/{id}/toggle-status")
     public Result<ClauseTemplateVO> toggleStatus(@ApiParam("模板ID") @PathVariable("id") Long templateId) {
         return Result.success(clauseTemplateService.toggleStatus(templateId));
     }
 
-    @ApiOperation("创建补充约定模板")
+    @ApiOperation(value = "创建补充约定模板", notes = "创建合同补充约定的模板，支持变量占位符。创建后默认启用")
     @PostMapping
     public Result<ClauseTemplateVO> create(@Valid @RequestBody ClauseTemplateRequest request) {
         return Result.success(clauseTemplateService.create(request));
     }
 
-    @ApiOperation("更新补充约定模板")
+    @ApiOperation(value = "更新补充约定模板",
+            notes = "更新模板的标题和内容。已被合同引用的模板更新不影响已创建的合同（合同记录的是快照内容）。\n\n**权限**：需管理员登录。")
     @PutMapping("/{id}")
     public Result<ClauseTemplateVO> update(
             @ApiParam("模板ID") @PathVariable("id") Long templateId,
@@ -53,7 +55,7 @@ public class AdminClauseTemplateController {
         return Result.success(clauseTemplateService.update(templateId, request));
     }
 
-    @ApiOperation("删除补充约定模板")
+    @ApiOperation(value = "删除补充约定模板", notes = "软删除模板。已被合同引用的模板仍可删除，不影响已创建的合同")
     @DeleteMapping("/{id}")
     public Result<Void> delete(@ApiParam("模板ID") @PathVariable("id") Long templateId) {
         clauseTemplateService.delete(templateId);

`hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java` (M)

接口变更 diff：

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java b/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java
index a6a6dbe..437717e 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java
@@ -30,19 +30,20 @@ public class AdminContractController {
 
     private final ContractService contractService;
 
-    @ApiOperation("可用旅行社列表")
+    @ApiOperation(value = "可用旅行社列表", notes = "返回系统配置的旅行社列表，创建合同时选择签约旅行社")
     @GetMapping("/agencies")
     public Result<List<ContractPlatformProperties.AgencyInfo>> listAgencies() {
         return Result.success(contractService.listAgencies());
     }
 
-    @ApiOperation("合同模板列表")
+    @ApiOperation(value = "合同模板列表", notes = "返回合同平台可用的合同模板列表，创建合同时选择模板")
     @GetMapping("/templates")
     public Result<List<ContractTemplateVO>> listTemplates() {
         return Result.success(contractService.listTemplates());
     }
 
-    @ApiOperation("创建合同(标准模式)")
+    @ApiOperation(value = "创建合同(标准模式)", notes = "标准电子签约流程：创建合同 → 平台生成合同PDF → 发送签署短信给出行人 → 出行人在线签署 → 回调更新状态。"
+            + "状态流转：CREATED → SIGNING → SIGNED")
     @PostMapping("/create")
     public Result<ContractDetailVO> createContract(
             @ApiParam("创建合同请求") @Valid @RequestBody CreateContractRequest request,
@@ -51,7 +52,8 @@ public class AdminContractController {
         return Result.success(contractService.createContract(request, adminId));
     }
 
-    @ApiOperation("报备合同(同步模式)")
+    @ApiOperation(value = "报备合同(同步模式)", notes = "线下签约模式：创建合同记录 → 管理员上传已签署的PDF → 同步到12301报备平台。"
+            + "状态流转：CREATED → UPLOADED → REPORTED")
     @PostMapping("/report")
     public Result<ContractDetailVO> reportContract(
             @ApiParam("报备合同请求") @Valid @RequestBody ReportContractRequest request,
@@ -60,49 +62,51 @@ public class AdminContractController {
         return Result.success(contractService.reportContract(request, adminId));
     }
 
-    @ApiOperation("合同列表")
+    @ApiOperation(value = "合同列表", notes = "分页查询合同记录，支持按订单号、合同状态、旅行社筛选\n\n**关联字典**：\n- contract_status：合同状态（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<ContractVO>> listContracts(@ApiParam("合同查询条件") ContractQueryRequest request) {
         return Result.success(contractService.listContracts(request));
     }
 
-    @ApiOperation("合同详情")
+    @ApiOperation(value = "合同详情", notes = "**关联字典**：\n- contract_status：合同状态（显示）")
     @GetMapping("/{id}")
     public Result<ContractDetailVO> getContractDetail(@ApiParam("合同ID") @PathVariable("id") Long contractId) {
         return Result.success(contractService.getContractDetail(contractId));
     }
 
-    @ApiOperation("按订单查询合同")
+    @ApiOperation(value = "按订单查询合同",
+            notes = "查询指定订单下的所有合同记录（含已作废），按创建时间倒序排列。用于订单详情页展示合同历史。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- contract_status：合同状态（列表显示）")
     @GetMapping("/by-order/{orderId}")
     public Result<List<ContractVO>> getByOrder(@ApiParam("订单ID") @PathVariable Long orderId) {
         return Result.success(contractService.getByOrderId(orderId));
     }
 
-    @ApiOperation("获取订单有效合同")
+    @ApiOperation(value = "获取订单有效合同",
+            notes = "返回订单当前有效的合同（非作废状态的最新合同），用于检查订单是否已有签署中或已签署的合同。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- contract_status：合同状态（显示）")
     @GetMapping("/active-by-order/{orderId}")
     public Result<ContractVO> getActiveByOrder(@ApiParam("订单ID") @PathVariable Long orderId) {
         return Result.success(contractService.getActiveContractByOrderId(orderId));
     }
 
-    @ApiOperation("刷新合同状态(从平台同步)")
+    @ApiOperation(value = "刷新合同状态(从平台同步)", notes = "主动查询合同平台的最新签署状态并同步到本地，适用于回调未到达的场景")
     @GetMapping("/{id}/status")
     public Result<ContractVO> refreshStatus(@ApiParam("合同ID") @PathVariable("id") Long contractId) {
         return Result.success(contractService.refreshStatus(contractId));
     }
 
-    @ApiOperation("作废合同")
+    @ApiOperation(value = "作废合同", notes = "将合同标记为作废状态（不可恢复）。作废后该合同不再有效，可重新为订单创建新合同")
     @PostMapping("/{id}/invalidate")
     public Result<ContractVO> invalidateContract(@ApiParam("合同ID") @PathVariable("id") Long contractId) {
         return Result.success(contractService.invalidateContract(contractId));
     }
 
-    @ApiOperation("重发签署短信")
+    @ApiOperation(value = "重发签署短信", notes = "重新发送签署短信给出行人，用于签署短信过期或未收到的场景。仅SIGNING状态的合同可操作")
     @PostMapping("/{id}/resend-sms")
     public Result<Boolean> resendSms(@ApiParam("合同ID") @PathVariable("id") Long contractId) {
         return Result.success(contractService.resendSms(contractId));
     }
 
-    @ApiOperation("上传已签署PDF(同步模式)")
+    @ApiOperation(value = "上传已签署PDF(同步模式)", notes = "同步模式专用：上传线下签署完成的合同PDF文件，上传后合同状态变为UPLOADED，可进一步报备")
     @PostMapping("/{id}/upload-pdf")
     public Result<ContractVO> uploadPdf(
             @ApiParam("合同ID") @PathVariable("id") Long contractId,

`hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java` (M)

接口变更 diff：

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java b/hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java
index 8415d27..bad13a5 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java
@@ -11,7 +11,7 @@ import org.springframework.web.bind.annotation.*;
 
 import javax.validation.Valid;
 
-@Api(tags = "【回调接口】合同回调")
+@Api(tags = "【回调接口】合同回调", hidden = true)
 @Slf4j
 @RestController
 @RequestMapping("/contract/callback")
@@ -20,7 +20,7 @@ public class ContractCallbackController {
 
     private final ContractCallbackService callbackService;
 
-    @ApiOperation("12301合同状态回调")
+    @ApiOperation(value = "12301合同状态回调", notes = "接收12301全国旅游监管平台的合同签署状态回调。出行人签署完成后平台推送状态变更到此接口，自动更新本地合同状态")
     @PostMapping("/12301")
     public ResponseEntity<String> handle12301Callback(@Valid @RequestBody ContractCallbackPayload payload) {
         log.info("Received 12301 callback: contractNumber={}, state={}",

`hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java` (M)

接口变更 diff：

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java b/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java
index 8929f18..3c25a33 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java
@@ -11,7 +11,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "【内部接口】合同（Feign调用）")
+@Api(tags = "【内部接口】合同（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/contract")
 @RequiredArgsConstructor
@@ -19,19 +19,19 @@ public class InternalContractController {
 
     private final ContractService contractService;
 
-    @ApiOperation("按订单查询合同(内部调用)")
+    @ApiOperation(value = "按订单查询合同(内部调用)", notes = "**关联字典**：\n- contract_status：合同状态（返回字段）")
     @GetMapping("/by-order/{orderId}")
     public Result<List<ContractVO>> getByOrder(@PathVariable Long orderId) {
         return Result.success(contractService.getByOrderId(orderId));
     }
 
-    @ApiOperation("按订单批量查询合同(内部调用)")
+    @ApiOperation(value = "按订单批量查询合同(内部调用)", notes = "**关联字典**：\n- contract_status：合同状态（返回字段）")
     @PostMapping("/by-orders")
     public Result<Map<Long, List<ContractVO>>> getByOrders(@RequestBody List<Long> orderIds) {
         return Result.success(contractService.getByOrderIds(orderIds));
     }
 
-    @ApiOperation("检查订单是否有已签署合同(内部调用)")
+    @ApiOperation(value = "检查订单是否有已签署合同(内部调用)", notes = "检查订单是否存在有效签署的合同（SIGNED/REPORTED/UPLOADED状态），用于订单流程中的合同校验")
     @GetMapping("/has-signed/{orderId}")
     public Result<Boolean> hasSigned(@PathVariable Long orderId) {
         List<ContractVO> contracts = contractService.getByOrderId(orderId);
@@ -41,7 +41,7 @@ public class InternalContractController {
         return Result.success(signed);
     }
 
-    @ApiOperation("按订单作废所有有效合同(级联调用)")
+    @ApiOperation(value = "按订单作废所有有效合同(级联调用)", notes = "订单取消或退款时级联作废该订单下所有有效合同，reason参数记录作废原因")
     @PostMapping("/invalidate/{orderId}")
     public Result<Void> invalidateByOrder(@PathVariable Long orderId,
                                            @RequestParam(value = "reason", required = false) String reason) {

`hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java` (M)

接口变更 diff：

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java b/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java
index 90d323c..bbb5883 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java
@@ -16,7 +16,7 @@ import java.util.Map;
  * C端合同内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "【内部接口】小程序合同（Feign调用）")
+@Api(tags = "【内部接口】小程序合同（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/contract")
 @RequiredArgsConstructor
@@ -24,7 +24,7 @@ public class InternalMpContractController {
 
     private final ContractService contractService;
 
-    @ApiOperation("用户合同列表")
+    @ApiOperation(value = "用户合同列表", notes = "**关联字典**：\n- contract_status：合同状态（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<ContractVO>> listContracts(
             @RequestParam Long userId,
@@ -34,7 +34,7 @@ public class InternalMpContractController {
         return Result.success(contractService.listUserContracts(userId, status, page, pageSize));
     }
 
-    @ApiOperation("用户合同详情")
+    @ApiOperation(value = "用户合同详情", notes = "**关联字典**：\n- contract_status：合同状态（显示）")
     @GetMapping("/{id}")
     public Result<ContractDetailVO> getContractDetail(
             @PathVariable("id") Long contractId,
@@ -42,7 +42,7 @@ public class InternalMpContractController {
         return Result.success(contractService.getUserContractDetail(contractId, userId));
     }
 
-    @ApiOperation("按订单查合同（返回最新有效合同）")
+    @ApiOperation(value = "按订单查合同（返回最新有效合同）", notes = "**关联字典**：\n- contract_status：合同状态（显示）")
     @GetMapping("/by-order/{orderId}")
     public Result<ContractVO> getContractByOrder(
             @PathVariable Long orderId,
@@ -50,7 +50,7 @@ public class InternalMpContractController {
         return Result.success(contractService.getUserContractByOrderId(orderId, userId));
     }
 
-    @ApiOperation("按订单查所有有效合同（TOUR+INSURANCE各一条）")
+    @ApiOperation(value = "按订单查所有有效合同（TOUR+INSURANCE各一条）", notes = "**关联字典**：\n- contract_status：合同状态（显示）")
     @GetMapping("/by-order/{orderId}/all")
     public Result<java.util.List<ContractVO>> getContractsByOrder(
             @PathVariable Long orderId,
@@ -58,7 +58,8 @@ public class InternalMpContractController {
         return Result.success(contractService.getUserContractsByOrderId(orderId, userId));
     }
 
-    @ApiOperation("重新发送合同签署短信")
+    @ApiOperation(value = "重新发送合同签署短信",
+            notes = "内部服务间调用。小程序端用户请求重发签署短信，用于签署链接过期或短信未收到的场景。仅SIGNING状态的合同可操作。\n\n**关联字典**：\n- contract_status：合同状态（仅SIGNING可操作）")
     @PostMapping("/{contractId}/resend-sms")
     public Result<Boolean> resendContractSms(
             @PathVariable("contractId") Long contractId,

`hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java` (M)

接口变更 diff：

diff --git a/hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java b/hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java
index 5b04b02..c78b2d2 100644
--- a/hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java
+++ b/hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java
@@ -33,7 +33,7 @@ public class FileController {
     private final FileService fileService;
     private final FileRefService fileRefService;
 
-    @ApiOperation("请求上传凭证")
+    @ApiOperation(value = "请求上传凭证", notes = "上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求")
     @OperationLog(value = "请求上传凭证", module = "文件管理")
     @PostMapping("/upload/token")
     public Result<UploadTokenVO> requestUploadToken(
@@ -44,7 +44,7 @@ public class FileController {
         return Result.success(vo);
     }
 
-    @ApiOperation("确认上传完成")
+    @ApiOperation(value = "确认上传完成", notes = "上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储")
     @OperationLog(value = "确认上传", module = "文件管理")
     @PostMapping("/upload/confirm")
     public Result<FileVO> confirmUpload(
@@ -55,21 +55,21 @@ public class FileController {
         return Result.success(vo);
     }
 
-    @ApiOperation("文件列表（分页）")
+    @ApiOperation(value = "文件列表（分页）", notes = "支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回\n\n**关联字典**：\n- file_type：文件类型（列表筛选+显示）\n- file_status：文件状态（显示）")
     @GetMapping("/list")
     public Result<IPage<FileVO>> listFiles(@ApiParam("文件查询条件") @Valid FileQueryRequest request) {
         IPage<FileVO> page = fileService.listFiles(request);
         return Result.success(page);
     }
 
-    @ApiOperation("文件详情")
+    @ApiOperation(value = "文件详情", notes = "**关联字典**：\n- file_type：文件类型（显示）\n- file_status：文件状态（显示）")
     @GetMapping("/{fileId}")
     public Result<FileVO> getFileDetail(@ApiParam("文件ID") @PathVariable Long fileId) {
         FileVO vo = fileService.getFileDetail(fileId);
         return Result.success(vo);
     }
 
-    @ApiOperation("删除文件")
+    @ApiOperation(value = "删除文件", notes = "软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理")
     @OperationLog(value = "删除文件", module = "文件管理")
     @DeleteMapping("/{fileId}")
     public Result<Void> deleteFile(@ApiParam("文件ID") @PathVariable Long fileId) {
@@ -77,21 +77,21 @@ public class FileController {
         return Result.success(null);
     }
 
-    @ApiOperation("文件引用列表")
+    @ApiOperation(value = "文件引用列表", notes = "查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除")
     @GetMapping("/{fileId}/refs")
     public Result<List<FileRefVO>> getFileRefs(@ApiParam("文件ID") @PathVariable Long fileId) {
         List<FileRefVO> refs = fileRefService.getRefsByFileId(fileId);
         return Result.success(refs);
     }
 
-    @ApiOperation("存储统计")
+    @ApiOperation(value = "存储统计", notes = "返回文件总数、总存储空间、各类型文件占比等统计信息")
     @GetMapping("/stats")
     public Result<FileStatsVO> getStats() {
         FileStatsVO stats = fileService.getStats();
         return Result.success(stats);
     }
 
-    @ApiOperation("文件内容流式预览")
+    @ApiOperation(value = "文件内容流式预览", notes = "流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件")
     @GetMapping("/{fileId}/preview")
     public void previewContent(@ApiParam("文件ID") @PathVariable Long fileId, HttpServletResponse response) throws IOException {
         fileService.streamContent(fileId, response);

`hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java` (M)

接口变更 diff：

diff --git a/hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java b/hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java
index cf46b6b..3690ff3 100644
--- a/hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java
+++ b/hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java
@@ -30,7 +30,7 @@ import org.springframework.web.multipart.MultipartFile;
 import javax.validation.Valid;
 import java.util.List;
 
-@Api(tags = "【内部接口】文件（Feign调用）")
+@Api(tags = "【内部接口】文件（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/file")
 @RequiredArgsConstructor
@@ -40,28 +40,30 @@ public class InternalFileController {
     private final FileRefService fileRefService;
     private final ChunkUploadService chunkUploadService;
 
-    @ApiOperation("绑定文件到业务实体")
+    @ApiOperation(value = "绑定文件到业务实体", notes = "将文件与业务实体建立引用关系（如景区ID+封面图），同一文件可被多个业务实体引用")
     @PostMapping("/bindRefs")
     public Result<Void> bindRefs(@Valid @RequestBody BindRefsRequest request) {
         fileRefService.bindRefs(request.getBizType(), request.getBizId(), request.getFileIds());
         return Result.success(null);
     }
 
-    @ApiOperation("解绑业务实体的所有文件")
+    @ApiOperation(value = "解绑业务实体的所有文件", notes = "删除指定业务类型+业务ID下的所有文件引用关系，常用于业务实体删除时的级联清理")
     @PostMapping("/unbindRefs")
     public Result<Void> unbindRefs(@Valid @RequestBody UnbindRefsRequest request) {
         fileRefService.unbindRefs(request.getBizType(), request.getBizId());
         return Result.success(null);
     }
 
-    @ApiOperation("批量获取文件信息")
+    @ApiOperation(value = "批量获取文件信息",
+            notes = "内部服务间调用。根据文件ID列表批量查询文件信息（含OSS URL、文件名、类型等），用于其他服务获取关联文件的详细数据。")
     @PostMapping("/byIds")
     public Result<List<FileVO>> getFilesByIds(@Valid @RequestBody BatchFileRequest request) {
         List<FileVO> files = fileService.getFilesByIds(request.getFileIds());
         return Result.success(files);
     }
 
-    @ApiOperation("内部上传凭证（素材服务调用）")
+    @ApiOperation(value = "内部上传凭证（素材服务调用）",
+            notes = "内部服务间调用。素材服务代理调用，为指定管理员生成OSS上传预签名URL和临时凭证，用于素材库的文件上传流程。")
     @PostMapping("/upload/token")
     public Result<UploadTokenVO> requestUploadTokenInternal(
             @Valid @RequestBody UploadTokenRequest request,
@@ -69,7 +71,7 @@ public class InternalFileController {
         return Result.success(fileService.requestUploadToken(request, adminId));
     }
 
-    @ApiOperation("内部直接上传文件（服务间调用）")
+    @ApiOperation(value = "内部直接上传文件（服务间调用）", notes = "服务间直接上传文件到OSS，跳过预签名流程。返回OSS公开访问URL，适用于后端生成的文件（如路线地图截图）")
     @PostMapping("/upload/direct")
     public Result<String> uploadDirect(
             @RequestParam("file") MultipartFile file,
@@ -78,7 +80,8 @@ public class InternalFileController {
         return Result.success(vo.getOssUrl());
     }
 
-    @ApiOperation("内部确认上传（素材服务调用）")
+    @ApiOperation(value = "内部确认上传（素材服务调用）",
+            notes = "内部服务间调用。素材服务代理调用，确认文件已上传至OSS并创建文件记录。支持MD5去重。")
     @PostMapping("/upload/confirm")
     public Result<FileVO> confirmUploadInternal(
             @Valid @RequestBody UploadConfirmRequest request,
@@ -88,7 +91,7 @@ public class InternalFileController {
 
     // ==================== 分片上传 ====================
 
-    @ApiOperation("分片上传-初始化")
+    @ApiOperation(value = "分片上传-初始化", notes = "大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用complete接口合并")
     @PostMapping("/upload/chunk/init")
     public Result<ChunkUploadInitVO> chunkUploadInit(
             @Valid @RequestBody ChunkUploadInitRequest request,
@@ -96,7 +99,7 @@ public class InternalFileController {
         return Result.success(chunkUploadService.initChunkUpload(request, adminId));
     }
 
-    @ApiOperation("分片上传-上传分片")
+    @ApiOperation(value = "分片上传-上传分片", notes = "大文件上传第二步：逐个上传分片，返回分片的ETag用于后续合并校验。支持断点续传，已上传的分片无需重传")
     @PostMapping("/upload/chunk")
     public Result<ChunkUploadPartVO> chunkUploadPart(
             @RequestParam("uploadId") String uploadId,
@@ -105,14 +108,14 @@ public class InternalFileController {
         return Result.success(chunkUploadService.uploadChunk(uploadId, chunkIndex, chunk));
     }
 
-    @ApiOperation("分片上传-完成合并")
+    @ApiOperation(value = "分片上传-完成合并", notes = "大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建文件记录")
     @PostMapping("/upload/chunk/complete")
     public Result<FileVO> chunkUploadComplete(
             @Valid @RequestBody ChunkUploadCompleteRequest request) {
         return Result.success(chunkUploadService.completeChunkUpload(request.getUploadId()));
     }
 
-    @ApiOperation("分片上传-取消")
+    @ApiOperation(value = "分片上传-取消", notes = "取消分片上传任务，清理已上传的分片数据和OSS临时文件")
     @PostMapping("/upload/chunk/cancel")
     public Result<Void> chunkUploadCancel(
             @Valid @RequestBody ChunkUploadCancelRequest request) {

`hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java` (M)

接口变更 diff：

diff --git a/hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java b/hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java
index b78e094..73b8a70 100644
--- a/hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java
+++ b/hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java
@@ -23,7 +23,7 @@ public class MpFileController {
 
     private final FileService fileService;
 
-    @ApiOperation("上传文件（C端用户）")
+    @ApiOperation(value = "上传文件（C端用户）", notes = "小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar")
     @PostMapping("/upload")
     public Result<FileVO> upload(
             @ApiParam("上传文件") @RequestParam("file") MultipartFile file,
@@ -34,7 +34,8 @@ public class MpFileController {
         return Result.success(vo);
     }
 
-    @ApiOperation("文件内容流式预览")
+    @ApiOperation(value = "文件内容流式预览",
+            notes = "流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。")
     @GetMapping("/{fileId}/preview")
     public void previewContent(@ApiParam("文件ID") @PathVariable Long fileId, HttpServletResponse response) throws IOException {
         fileService.streamContent(fileId, response);

`hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java` (M)

接口变更 diff：

diff --git a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java
index a96b208..10fe073 100644
--- a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java
+++ b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java
@@ -22,19 +22,20 @@ public class AdminGuideArticleController {
 
     private final GuideArticleService articleService;
 
-    @ApiOperation("文章列表")
+    @ApiOperation(value = "文章列表", notes = "分页查询攻略文章，支持按分类、状态、关键词筛选\n\n**关联字典**：\n- wiki_status：文章状态（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<GuideArticleListVO>> listArticles(@Valid ArticleQueryRequest query) {
         return Result.success(articleService.listArticles(query));
     }
 
-    @ApiOperation("文章详情")
+    @ApiOperation(value = "文章详情", notes = "**关联字典**：\n- wiki_status：文章状态（显示）")
     @GetMapping("/{articleId}")
     public Result<GuideArticleVO> getArticle(@PathVariable Long articleId) {
         return Result.success(articleService.getArticle(articleId));
     }
 
-    @ApiOperation("创建文章")
+    @ApiOperation(value = "创建文章",
+            notes = "创建攻略文章，需指定分类。创建后默认为草稿状态，需手动发布后小程序端才可见。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- wiki_status：文章状态（创建后默认DRAFT）")
     @PostMapping
     public Result<GuideArticleVO> createArticle(
             @Valid @RequestBody ArticleCreateRequest request,
@@ -43,7 +44,8 @@ public class AdminGuideArticleController {
         return Result.success(articleService.createArticle(request, adminId));
     }
 
-    @ApiOperation("更新文章")
+    @ApiOperation(value = "更新文章",
+            notes = "更新攻略文章的标题、内容、封面图、分类等信息。已发布的文章更新后立即生效。\n\n**权限**：需管理员登录。")
     @PutMapping("/{articleId}")
     public Result<GuideArticleVO> updateArticle(
             @PathVariable Long articleId,
@@ -51,14 +53,15 @@ public class AdminGuideArticleController {
         return Result.success(articleService.updateArticle(articleId, request));
     }
 
-    @ApiOperation("删除文章")
+    @ApiOperation(value = "删除文章",
+            notes = "软删除攻略文章，同时清除文章的标签关联。\n\n**权限**：需管理员登录。")
     @DeleteMapping("/{articleId}")
     public Result<Void> deleteArticle(@PathVariable Long articleId) {
         articleService.deleteArticle(articleId);
         return Result.success();
     }
 
-    @ApiOperation("发布/下架")
+    @ApiOperation(value = "发布/下架", notes = "切换文章发布状态。发布后小程序端可见，下架后小程序端不再展示但管理端仍可查看\n\n**关联字典**：\n- wiki_status：文章状态（状态切换）")
     @PutMapping("/{articleId}/status")
     public Result<Void> updateStatus(
             @PathVariable Long articleId,
@@ -67,7 +70,7 @@ public class AdminGuideArticleController {
         return Result.success();
     }
 
-    @ApiOperation("设置推荐")
+    @ApiOperation(value = "设置推荐", notes = "设置/取消文章推荐。推荐文章会在小程序首页和推荐列表中优先展示")
     @PutMapping("/{articleId}/recommend")
     public Result<Void> updateRecommend(
             @PathVariable Long articleId,
@@ -76,7 +79,7 @@ public class AdminGuideArticleController {
         return Result.success();
     }
 
-    @ApiOperation("设置置顶")
+    @ApiOperation(value = "设置置顶", notes = "设置/取消文章置顶。置顶文章在分类列表中始终排在最前面")
     @PutMapping("/{articleId}/top")
     public Result<Void> updateTop(
             @PathVariable Long articleId,

`hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java` (M)

接口变更 diff：

diff --git a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java
index 8b849da..0eddd64 100644
--- a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java
+++ b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java
@@ -24,19 +24,20 @@ public class AdminGuideCategoryController {
 
     private final GuideCategoryService categoryService;
 
-    @ApiOperation("分类列表")
+    @ApiOperation(value = "分类列表", notes = "返回全部攻略分类（含启用和停用），按排序值升序排列\n\n**关联字典**：\n- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用）")
     @GetMapping("/list")
     public Result<List<GuideCategoryVO>> listCategories() {
         return Result.success(categoryService.listCategories());
     }
 
-    @ApiOperation("启用的分类列表")
+    @ApiOperation(value = "启用的分类列表", notes = "仅返回状态为启用的分类，创建文章时用于选择分类")
     @GetMapping("/enabled")
     public Result<List<GuideCategoryVO>> listEnabledCategories() {
         return Result.success(categoryService.listEnabledCategories());
     }
 
-    @ApiOperation("创建分类")
+    @ApiOperation(value = "创建分类",
+            notes = "创建攻略分类，分类名称不可重复。创建后默认启用，排序值越小越靠前。\n\n**权限**：需管理员登录。")
     @PostMapping
     public Result<GuideCategoryVO> createCategory(
             @Valid @RequestBody CategoryCreateRequest request,
@@ -45,7 +46,8 @@ public class AdminGuideCategoryController {
         return Result.success(categoryService.createCategory(request, adminId));
     }
 
-    @ApiOperation("更新分类")
+    @ApiOperation(value = "更新分类",
+            notes = "更新攻略分类的名称、图标、描述等信息。\n\n**权限**：需管理员登录。")
     @PutMapping("/{categoryId}")
     public Result<GuideCategoryVO> updateCategory(
             @PathVariable Long categoryId,
@@ -53,14 +55,14 @@ public class AdminGuideCategoryController {
         return Result.success(categoryService.updateCategory(categoryId, request));
     }
 
-    @ApiOperation("删除分类")
+    @ApiOperation(value = "删除分类", notes = "删除分类前需确保分类下无文章，否则删除失败")
     @DeleteMapping("/{categoryId}")
     public Result<Void> deleteCategory(@PathVariable Long categoryId) {
         categoryService.deleteCategory(categoryId);
         return Result.success();
     }
 
-    @ApiOperation("更新分类状态")
+    @ApiOperation(value = "更新分类状态", notes = "启用或停用分类。停用后该分类下的文章不会在小程序端展示，但不影响已有文章\n\n**关联字典**：\n- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用）")
     @PutMapping("/{categoryId}/status")
     public Result<Void> updateStatus(
             @PathVariable Long categoryId,
@@ -69,7 +71,8 @@ public class AdminGuideCategoryController {
         return Result.success();
     }
 
-    @ApiOperation("更新分类排序")
+    @ApiOperation(value = "更新分类排序",
+            notes = "更新分类的排序值，排序值越小越靠前。影响小程序端分类导航的展示顺序。\n\n**权限**：需管理员登录。")
     @PutMapping("/{categoryId}/sort")
     public Result<Void> updateSort(
             @PathVariable Long categoryId,

`hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java` (M)

接口变更 diff：

diff --git a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java
index acd32b1..d747ae4 100644
--- a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java
+++ b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java
@@ -23,19 +23,20 @@ public class AdminGuideTagController {
 
     private final GuideTagService tagService;
 
-    @ApiOperation("系统标签列表")
+    @ApiOperation(value = "系统标签列表", notes = "返回管理员创建的系统标签（不含用户自定义标签），用于标签管理页")
     @GetMapping("/managed")
     public Result<List<GuideTagVO>> listManagedTags() {
         return Result.success(tagService.listManagedTags());
     }
 
-    @ApiOperation("所有标签列表")
+    @ApiOperation(value = "所有标签列表", notes = "返回全部标签（含系统标签和用户自定义标签），用于文章编辑时的标签选择器")
     @GetMapping("/all")
     public Result<List<GuideTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建标签")
+    @ApiOperation(value = "创建标签",
+            notes = "创建攻略系统标签，标签名称不可重复。创建后可用于文章分类和筛选。\n\n**权限**：需管理员登录。")
     @PostMapping
     public Result<GuideTagVO> createTag(
             @Valid @RequestBody TagCreateRequest request,
@@ -44,7 +45,8 @@ public class AdminGuideTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("更新标签")
+    @ApiOperation(value = "更新标签",
+            notes = "更新标签名称。标签名称不可与其他已有标签重复。\n\n**权限**：需管理员登录。")
     @PutMapping("/{tagId}")
     public Result<GuideTagVO> updateTag(
             @PathVariable Long tagId,
@@ -52,14 +54,15 @@ public class AdminGuideTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签",
+            notes = "删除标签并自动解除与所有文章的关联关系。\n\n**权限**：需管理员登录。")
     @DeleteMapping("/{tagId}")
     public Result<Void> deleteTag(@PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("更新文章标签")
+    @ApiOperation(value = "更新文章标签", notes = "全量替换文章的标签关联，传入新的标签ID列表（空数组表示清除所有标签）")
     @PutMapping("/article/{articleId}")
     public Result<Void> updateArticleTags(
             @PathVariable Long articleId,

`hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java` (M)

接口变更 diff：

diff --git a/hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java b/hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java
index 42c16dd..62838a6 100644
--- a/hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java
+++ b/hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java
@@ -16,7 +16,7 @@ import java.util.Map;
 /**
  * 内部接口 - 供 mp-service Feign 调用
  */
-@Api(tags = "【内部接口】攻略百科（Feign调用）")
+@Api(tags = "【内部接口】攻略百科（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/wiki")
 @RequiredArgsConstructor
@@ -25,13 +25,14 @@ public class InternalWikiController {
     private final GuideCategoryService categoryService;
     private final GuideArticleService articleService;
 
-    @ApiOperation("查询已启用的攻略分类列表")
+    @ApiOperation(value = "查询已启用的攻略分类列表",
+            notes = "内部服务间调用。返回所有状态为启用的攻略分类，供小程序端展示分类导航。\n\n**关联字典**：\n- common_status：通用状态（仅返回ACTIVE状态的分类）")
     @GetMapping("/categories")
     public Result<List<GuideCategoryVO>> listEnabledCategories() {
         return Result.success(categoryService.listEnabledCategories());
     }
 
-    @ApiOperation("分页查询指定分类下的已发布文章")
+    @ApiOperation(value = "分页查询指定分类下的已发布文章", notes = "**关联字典**：\n- wiki_status：文章状态（返回字段）")
     @GetMapping("/category/{categoryId}/articles")
     public Result<PageResult<Map<String, Object>>> listCategoryArticles(
             @PathVariable Long categoryId,
@@ -40,13 +41,14 @@ public class InternalWikiController {
         return Result.success(articleService.listPublishedArticlesByCategory(categoryId, page, pageSize));
     }
 
-    @ApiOperation("查询已发布文章详情")
+    @ApiOperation(value = "查询已发布文章详情", notes = "**关联字典**：\n- wiki_status：文章状态（返回字段）")
     @GetMapping("/article/{articleId}")
     public Result<Map<String, Object>> getArticle(@PathVariable Long articleId) {
         return Result.success(articleService.getPublishedArticle(articleId));
     }
 
-    @ApiOperation("查询推荐文章列表")
+    @ApiOperation(value = "查询推荐文章列表",
+            notes = "内部服务间调用。返回已发布且标记为推荐的文章列表，用于小程序首页推荐位展示。默认返回5条。")
     @GetMapping("/recommend-articles")
     public Result<List<Map<String, Object>>> listRecommendArticles(
             @RequestParam(defaultValue = "5") Integer limit) {

`hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java` (M)

接口变更 diff：

diff --git a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java
index 852da1c..1505c2c 100644
--- a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java
+++ b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java
@@ -48,7 +48,8 @@ public class AdminInsuranceController {
     private final InsuranceEntityProperties entityProperties;
     private final PolicyShareService policyShareService;
 
-    @ApiOperation("保险产品列表")
+    @ApiOperation(value = "保险产品列表",
+            notes = "分页查询已同步的保险产品，支持按是否境外筛选。产品数据来源于保游网同步。\n\n**权限**：需管理员登录。")
     @GetMapping("/products")
     public Result<PageResult<InsuranceProductVO>> listProducts(
             @ApiParam("页码") @RequestParam(defaultValue = "1") Integer page,
@@ -57,26 +58,30 @@ public class AdminInsuranceController {
         return Result.success(orderService.listProducts(page, pageSize, isOverseas));
     }
 
-    @ApiOperation("保险产品详情")
+    @ApiOperation(value = "保险产品详情",
+            notes = "返回保险产品完整信息，包含产品名称、保险公司、保障范围、适用地区等。\n\n**权限**：需管理员登录。")
     @GetMapping("/products/{id}")
     public Result<InsuranceProductVO> getProduct(@ApiParam("保险产品ID") @PathVariable("id") Long productId) {
         return Result.success(orderService.getProductDetail(productId));
     }
 
-    @ApiOperation("保险产品计划及费率")
+    @ApiOperation(value = "保险产品计划及费率",
+            notes = "返回指定保险产品的所有投保计划及对应费率表，包含不同天数区间的保费价格。投保下单前需选择具体计划。\n\n**权限**：需管理员登录。")
     @GetMapping("/products/{id}/plans")
     public Result<List<InsurancePlanVO>> getProductPlans(@ApiParam("保险产品ID") @PathVariable("id") Long productId) {
         return Result.success(orderService.getProductPlans(productId));
     }
 
-    @ApiOperation("从保游网同步产品数据")
+    @ApiOperation(value = "从保游网同步产品数据",
+            notes = "手动触发从保游网API拉取最新保险产品数据（含计划和费率），同步到本地数据库。返回同步的产品数量。\n\n**权限**：需管理员登录。")
     @PostMapping("/sync-products")
     public Result<Integer> syncProducts() {
         int count = syncService.syncAll();
         return Result.success(count);
     }
 
-    @ApiOperation("投保公司主体列表")
+    @ApiOperation(value = "投保公司主体列表",
+            notes = "返回系统配置的投保公司主体列表（来自Nacos配置），投保下单时选择以哪个公司主体投保。每个主体包含编码、公司名称和商户ID。\n\n**权限**：需管理员登录。")
     @GetMapping("/entities")
     public Result<List<Map<String, String>>> listEntities() {
         List<Map<String, String>> list = entityProperties.getList().stream().map(e -> {
@@ -91,7 +96,7 @@ public class AdminInsuranceController {
         return Result.success(list);
     }
 
-    @ApiOperation("投保下单(每人独立保单)")
+    @ApiOperation(value = "投保下单(每人独立保单)", notes = "**关联字典**：\n- gender：性别（被保人信息）\n- id_card_type：证件类型（被保人信息）")
     @PostMapping("/purchase")
     public Result<List<InsuranceOrderDetailVO>> purchase(
             @ApiParam("投保请求") @Valid @RequestBody PurchaseInsuranceRequest request,
@@ -100,43 +105,48 @@ public class AdminInsuranceController {
         return Result.success(orderService.purchase(request, adminId));
     }
 
-    @ApiOperation("退保")
+    @ApiOperation(value = "退保",
+            notes = "对单个保险订单发起退保，调用保游网退保API。退保成功后保险状态变为CANCELLED。\n\n**权限**：需管理员登录。\n**注意**：已生效的保单退保可能产生手续费。\n\n**关联字典**：\n- insurance_status：保险状态（状态流转）")
     @PostMapping("/cancel/{id}")
     public Result<InsuranceOrderVO> cancel(@ApiParam("保险订单ID") @PathVariable("id") Long insuranceOrderId) {
         return Result.success(orderService.cancel(insuranceOrderId));
     }
 
-    @ApiOperation("保险订单列表")
+    @ApiOperation(value = "保险订单列表", notes = "**关联字典**：\n- insurance_status：保险状态（列表筛选+显示）")
     @GetMapping("/orders")
     public Result<PageResult<InsuranceOrderVO>> listOrders(@ApiParam("查询条件") InsuranceQueryRequest request) {
         return Result.success(orderService.listOrders(request));
     }
 
-    @ApiOperation("保险订单详情(含被保人)")
+    @ApiOperation(value = "保险订单详情(含被保人)", notes = "**关联字典**：\n- insurance_status：保险状态（显示）\n- gender：性别（被保人信息显示）\n- id_card_type：证件类型（被保人信息显示）")
     @GetMapping("/orders/{id}")
     public Result<InsuranceOrderDetailVO> getOrderDetail(@ApiParam("保险订单ID") @PathVariable("id") Long insuranceOrderId) {
         return Result.success(orderService.getOrderDetail(insuranceOrderId));
     }
 
-    @ApiOperation("按旅行订单查询保险单")
+    @ApiOperation(value = "按旅行订单查询保险单",
+            notes = "根据旅行订单ID查询关联的所有保险订单列表。在订单详情页展示保险购买情况。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- insurance_status：保险状态（列表显示）")
     @GetMapping("/orders/by-order/{orderId}")
     public Result<List<InsuranceOrderVO>> getByOrder(@ApiParam("旅行订单ID") @PathVariable Long orderId) {
         return Result.success(orderService.getByOrderId(orderId));
     }
 
-    @ApiOperation("查询订单保险保障(含被保人详情)")
+    @ApiOperation(value = "查询订单保险保障(含被保人详情)",
+            notes = "返回订单维度的保险保障汇总信息，包含覆盖人数、保障期间、每位被保人的保单明细。用于订单详情页的保险保障展示。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- insurance_status：保险状态（显示）\n- gender：性别（被保人信息显示）\n- id_card_type：证件类型（被保人信息显示）")
     @GetMapping("/coverage/{orderId}")
     public Result<InsuranceCoverageVO> getCoverage(@ApiParam("旅行订单ID") @PathVariable Long orderId) {
         return Result.success(orderService.getCoverageByOrderId(orderId));
     }
 
-    @ApiOperation("保费试算(本地费率)")
+    @ApiOperation(value = "保费试算(本地费率)",
+            notes = "根据保险计划、投保天数和人数，使用本地同步的费率表试算保费。不调用保游网API，用于投保前的费用预估。\n\n**权限**：需管理员登录。")
     @PostMapping("/trial-price")
     public Result<Map<String, Object>> trialPrice(@ApiParam("试算请求") @Valid @RequestBody TrialPriceRequest request) {
         return Result.success(orderService.trialPrice(request));
     }
 
-    @ApiOperation("查询保游网账户余额")
+    @ApiOperation(value = "查询保游网账户余额",
+            notes = "查询保游网平台的账户余额，用于管理端展示当前可用投保额度。查询失败时返回null（非关键信息，不影响业务）。\n\n**权限**：需管理员登录。")
     @GetMapping("/balance")
     public Result<JsonNode> getBalance() {
         try {
@@ -152,13 +162,15 @@ public class AdminInsuranceController {
         return Result.success(null);
     }
 
-    @ApiOperation("下载保单PDF(Base64)")
+    @ApiOperation(value = "下载保单PDF(Base64)",
+            notes = "从保游网下载指定保险订单的电子保单PDF，以Base64编码返回。前端可解码后展示或提供下载。\n\n**权限**：需管理员登录。")
     @GetMapping("/policy/{id}/download")
     public Result<String> downloadPolicy(@ApiParam("保险订单ID") @PathVariable("id") Long insuranceOrderId) {
         return Result.success(orderService.downloadPolicy(insuranceOrderId));
     }
 
-    @ApiOperation("获取保游网充值链接(旧接口,保留兼容)")
+    @ApiOperation(value = "获取保游网充值链接(旧接口,保留兼容)",
+            notes = "返回保游网平台的充值页面URL。此为旧版接口，保留用于向后兼容，推荐使用在线充值接口。\n\n**权限**：需管理员登录。")
     @GetMapping("/recharge-url")
     public Result<String> getRechargeUrl() {
         String url = baoyouProperties.getRechargeUrl();
@@ -168,13 +180,15 @@ public class AdminInsuranceController {
         return Result.success(url);
     }
 
-    @ApiOperation("在线充值(调用保游网支付API)")
+    @ApiOperation(value = "在线充值(调用保游网支付API)",
+            notes = "调用保游网在线充值API，生成充值支付链接。支持选择支付方式（支付宝/微信），充值完成后账户余额自动更新。\n\n**权限**：需管理员登录。")
     @PostMapping("/recharge")
     public Result<Map<String, Object>> recharge(@ApiParam("充值请求") @Valid @RequestBody RechargeRequest request) {
         return Result.success(orderService.recharge(request.getMoney(), request.getPayType(), request.getBackUrl()));
     }
 
-    @ApiOperation("分享保单(合并某出行人所有有效保单PDF,上传OSS返回链接)")
+    @ApiOperation(value = "分享保单(合并某出行人所有有效保单PDF,上传OSS返回链接)",
+            notes = "合并指定出行人的所有有效保单PDF为一个文件，上传至OSS后返回公开访问链接。用于管理端分享保单给出行人。\n\n**权限**：需管理员登录。")
     @PostMapping("/share-policy")
     public Result<PolicyShareVO> sharePolicy(
             @ApiParam("分享保单请求") @Valid @RequestBody SharePolicyRequest request) {

`hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java` (M)

接口变更 diff：

diff --git a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java
index 9497720..04db6d6 100644
--- a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java
+++ b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java
@@ -24,26 +24,30 @@ public class AdminInsuranceSchemeController {
 
     private final InsuranceSchemeService schemeService;
 
-    @ApiOperation("活跃方案列表(下拉选择用)")
+    @ApiOperation(value = "活跃方案列表(下拉选择用)",
+            notes = "返回所有状态为启用的保险方案模板，用于投保下单时的方案下拉选择。\n\n**权限**：需管理员登录。")
     @GetMapping("/list")
     public Result<List<InsuranceSchemeVO>> listActiveSchemes() {
         return Result.success(schemeService.listActiveSchemes());
     }
 
-    @ApiOperation("全部方案列表(管理用)")
+    @ApiOperation(value = "全部方案列表(管理用)",
+            notes = "返回所有保险方案模板（含启用和停用），用于方案管理页面展示和编辑。\n\n**权限**：需管理员登录。")
     @GetMapping("/list-all")
     public Result<List<InsuranceSchemeVO>> listAllSchemes() {
         return Result.success(schemeService.listAllSchemes());
     }
 
-    @ApiOperation("方案详情")
+    @ApiOperation(value = "方案详情",
+            notes = "返回单个保险方案模板的完整信息，包含方案名称、保险产品关联、天数规则、费率配置等。\n\n**权限**：需管理员登录。")
     @GetMapping("/{id}")
     public Result<InsuranceSchemeVO> getSchemeDetail(
             @ApiParam("方案ID") @PathVariable("id") Long schemeId) {
         return Result.success(schemeService.getSchemeDetail(schemeId));
     }
 
-    @ApiOperation("创建方案")
+    @ApiOperation(value = "创建方案",
+            notes = "创建保险方案模板，配置关联保险产品、投保天数规则和费率。创建后默认启用。\n\n**权限**：需管理员登录。")
     @PostMapping
     public Result<InsuranceSchemeVO> createScheme(
             @ApiParam("方案请求") @Valid @RequestBody InsuranceSchemeRequest request,
@@ -52,7 +56,8 @@ public class AdminInsuranceSchemeController {
         return Result.success(schemeService.createScheme(request, adminId));
     }
 
-    @ApiOperation("更新方案")
+    @ApiOperation(value = "更新方案",
+            notes = "更新保险方案模板的配置信息，包括方案名称、关联产品、天数规则、费率等。\n\n**权限**：需管理员登录。")
     @PutMapping("/{id}")
     public Result<InsuranceSchemeVO> updateScheme(
             @ApiParam("方案ID") @PathVariable("id") Long schemeId,
@@ -62,14 +67,16 @@ public class AdminInsuranceSchemeController {
         return Result.success(schemeService.updateScheme(schemeId, request, adminId));
     }
 
-    @ApiOperation("切换方案状态(启用/停用)")
+    @ApiOperation(value = "切换方案状态(启用/停用)",
+            notes = "切换保险方案模板的启用/停用状态。停用后不会出现在投保下单的方案选择列表中。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- common_status：通用状态（ACTIVE=启用/INACTIVE=停用）")
     @PutMapping("/{id}/toggle-status")
     public Result<InsuranceSchemeVO> toggleStatus(
             @ApiParam("方案ID") @PathVariable("id") Long schemeId) {
         return Result.success(schemeService.toggleStatus(schemeId));
     }
 
-    @ApiOperation("删除方案(软删除)")
+    @ApiOperation(value = "删除方案(软删除)",
+            notes = "软删除保险方案模板。已使用该方案创建的保险订单不受影响。\n\n**权限**：需管理员登录。")
     @DeleteMapping("/{id}")
     public Result<Void> deleteScheme(
             @ApiParam("方案ID") @PathVariable("id") Long schemeId) {
@@ -77,7 +84,8 @@ public class AdminInsuranceSchemeController {
         return Result.success(null);
     }
 
-    @ApiOperation("预览应用方案(解析日期+估算保费)")
+    @ApiOperation(value = "预览应用方案(解析日期+估算保费)",
+            notes = "根据方案模板和行程日期预览投保效果：解析实际投保起止日期、计算每人保费和总保费。用于投保前确认费用。\n\n**权限**：需管理员登录。")
     @PostMapping("/preview-apply")
     public Result<ApplySchemePreviewVO> previewApply(
             @ApiParam("预览请求") @Valid @RequestBody ApplySchemeRequest request) {

`hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java` (M)

接口变更 diff：

diff --git a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java
index 828cc04..d77d99e 100644
--- a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java
+++ b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java
@@ -16,7 +16,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "【内部接口】保险（Feign调用）")
+@Api(tags = "【内部接口】保险（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/insurance")
 @RequiredArgsConstructor
@@ -26,19 +26,22 @@ public class InternalInsuranceController {
     private final InsuranceProductSyncService syncService;
     private final PolicyShareService policyShareService;
 
-    @ApiOperation("按旅行订单查询保险单(内部调用)")
+    @ApiOperation(value = "按旅行订单查询保险单(内部调用)",
+            notes = "内部服务间调用。根据旅行订单ID查询关联的所有保险订单，返回保险状态、保费、保障期间等信息。\n\n**关联字典**：\n- insurance_status：保险状态（返回字段）")
     @GetMapping("/by-order/{orderId}")
     public Result<List<InsuranceOrderVO>> getByOrder(@ApiParam("旅行订单ID") @PathVariable Long orderId) {
         return Result.success(orderService.getByOrderId(orderId));
     }
 
-    @ApiOperation("按订单批量查询保险单(内部调用)")
+    @ApiOperation(value = "按订单批量查询保险单(内部调用)",
+            notes = "内部服务间调用。批量查询多个旅行订单的保险订单，返回Map结构（key=订单ID，value=保险单列表），用于订单列表页展示保险状态。")
     @PostMapping("/by-orders")
     public Result<Map<Long, List<InsuranceOrderVO>>> getByOrders(@RequestBody List<Long> orderIds) {
         return Result.success(orderService.getByOrderIds(orderIds));
     }
 
-    @ApiOperation("检查保险是否全覆盖(内部调用)")
+    @ApiOperation(value = "检查保险是否全覆盖(内部调用)",
+            notes = "内部服务间调用。根据出行人数和行程天数计算所需的人日数，与已投保的有效保单覆盖人日数对比，判断保险是否已全覆盖。")
     @GetMapping("/coverage-complete/{orderId}")
     public Result<Boolean> isCoverageComplete(
             @ApiParam("旅行订单ID") @PathVariable Long orderId,
@@ -57,7 +60,8 @@ public class InternalInsuranceController {
         return Result.success(coveredPersonDays >= requiredPersonDays);
     }
 
-    @ApiOperation("按订单批量退保(级联失效调用)")
+    @ApiOperation(value = "按订单批量退保(级联失效调用)",
+            notes = "内部服务间调用。旅行订单取消或退款时级联调用，将该订单下所有有效保险单批量退保（调用保游网退保API），记录退保原因。")
     @PostMapping("/invalidate/{orderId}")
     public Result<Void> invalidateInsurance(
             @ApiParam("旅行订单ID") @PathVariable Long orderId,
@@ -66,19 +70,22 @@ public class InternalInsuranceController {
         return Result.success(null);
     }
 
-    @ApiOperation("分享保单PDF(内部调用,返回base64)")
+    @ApiOperation(value = "分享保单PDF(内部调用,返回base64)",
+            notes = "内部服务间调用。合并指定出行人的所有有效保单PDF为一个文件，上传至OSS后返回下载链接和Base64内容，用于小程序端分享保单。")
     @PostMapping("/share-policy")
     public Result<PolicyShareVO> sharePolicy(@RequestBody SharePolicyRequest request) {
         return Result.success(policyShareService.sharePolicy(request));
     }
 
-    @ApiOperation("按订单获取所有保单PDF(内部调用,合并所有出行人)")
+    @ApiOperation(value = "按订单获取所有保单PDF(内部调用,合并所有出行人)",
+            notes = "内部服务间调用。将指定订单下所有出行人的有效保单PDF合并为一个文件，上传至OSS后返回下载链接，用于订单维度的保单查看。")
     @GetMapping("/share-policy-by-order/{orderId}")
     public Result<PolicyShareVO> sharePolicyByOrder(@PathVariable Long orderId) {
         return Result.success(policyShareService.sharePolicyByOrder(orderId));
     }
 
-    @ApiOperation("触发保险产品同步(内部调用/定时任务)")
+    @ApiOperation(value = "触发保险产品同步(内部调用/定时任务)",
+            notes = "内部服务间调用。从保游网API拉取最新保险产品数据（含计划和费率），同步到本地数据库。返回同步的产品数量。")
     @PostMapping("/sync-products")
     public Result<Integer> syncProducts() {
         int count = syncService.syncAll();

`hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java` (M)

接口变更 diff：

diff --git a/hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java b/hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java
index 08122a4..686a577 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java
@@ -22,7 +22,7 @@ import java.util.List;
  * Internal endpoints for Feign calls from other services (scenic, hotel, etc.).
  * Not exposed through gateway.
  */
-@Api(tags = "素材内部接口（Feign调用）")
+@Api(tags = "素材内部接口（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/material")
 @RequiredArgsConstructor
@@ -31,7 +31,7 @@ public class InternalMaterialController {
     private final MaterialRefService refService;
     private final MaterialService materialService;
 
-    @ApiOperation("绑定引用")
+    @ApiOperation(value = "绑定引用", notes = "将素材与业务实体建立引用关系（如景区ID+封面图），记录引用类型（COVER/GALLERY/DETAIL等）")
     @PostMapping("/ref/bind")
     public Result<Void> bindRef(
             @Valid @RequestBody RefBindRequest request,
@@ -40,7 +40,7 @@ public class InternalMaterialController {
         return Result.success();
     }
 
-    @ApiOperation("批量绑定引用")
+    @ApiOperation(value = "批量绑定引用", notes = "批量建立素材与业务实体的引用关系，常用于保存包含多张图片的业务数据")
     @PostMapping("/ref/batch-bind")
     public Result<Void> batchBindRefs(
             @Valid @RequestBody RefBatchBindRequest request,
@@ -49,7 +49,7 @@ public class InternalMaterialController {
         return Result.success();
     }
 
-    @ApiOperation("解绑引用")
+    @ApiOperation(value = "解绑引用", notes = "删除单个素材与业务实体的引用关系")
     @DeleteMapping("/ref/unbind")
     public Result<Void> unbindRef(@Valid @RequestBody RefUnbindRequest request) {
         refService.unbindRef(request.getMaterialId(), request.getBizType(),
@@ -57,14 +57,15 @@ public class InternalMaterialController {
         return Result.success();
     }
 
-    @ApiOperation("批量解绑引用")
+    @ApiOperation(value = "批量解绑引用", notes = "批量删除素材引用关系，常用于业务实体更新时先清除旧引用再绑定新引用")
     @DeleteMapping("/ref/batch-unbind")
     public Result<Void> batchUnbindRefs(@Valid @RequestBody RefBatchUnbindRequest request) {
         refService.batchUnbindRefs(request.getRefs());
         return Result.success();
     }
 
-    @ApiOperation("批量查询素材信息")
+    @ApiOperation(value = "批量查询素材信息",
+            notes = "内部服务间调用。根据素材ID列表批量查询素材信息，用于其他服务获取素材详情（如产品、景区等关联的素材数据）。")
     @PostMapping("/by-ids")
     public Result<List<MaterialVO>> getMaterialsByIds(@Valid @RequestBody BatchMaterialIdsRequest request) {
         return Result.success(materialService.getMaterialsByIds(request.getMaterialIds()));

`hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java` (M)

接口变更 diff：

diff --git a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java
index 03566eb..77fa5a6 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java
@@ -23,7 +23,7 @@ public class MaterialCategoryPermissionController {
 
     private final MaterialCategoryPermissionService permissionService;
 
-    @ApiOperation("获取角色的分类权限")
+    @ApiOperation(value = "获取角色的分类权限", notes = "仅超级管理员可操作。返回指定角色可访问的素材分类编码列表")
     @GetMapping("/{roleCode}")
     public Result<List<String>> getPermissions(
             @ApiParam("角色编码") @PathVariable String roleCode,
@@ -32,7 +32,7 @@ public class MaterialCategoryPermissionController {
         return Result.success(permissionService.getPermissionsByRoleCode(roleCode));
     }
 
-    @ApiOperation("更新角色的分类权限")
+    @ApiOperation(value = "更新角色的分类权限", notes = "仅超级管理员可操作。全量替换指定角色的素材分类访问权限，传入允许访问的分类编码列表")
     @PutMapping("/{roleCode}")
     public Result<Void> updatePermissions(
             @ApiParam("角色编码") @PathVariable String roleCode,

`hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java` (M)

接口变更 diff：

diff --git a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java
index 0fa7c7e..d79def9 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java
@@ -47,7 +47,7 @@ public class MaterialController {
 
     // ==================== Upload ====================
 
-    @ApiOperation("获取上传凭证")
+    @ApiOperation(value = "获取上传凭证", notes = "上传素材第一步：获取OSS预签名URL和凭证。前端使用凭证直传OSS后调用确认上传。支持基于角色的分类权限校验")
     @PostMapping("/upload/token")
     public Result<MaterialUploadTokenVO> requestUploadToken(
             @ApiParam("上传凭证请求") @Valid @RequestBody MaterialUploadTokenRequest request,
@@ -57,7 +57,7 @@ public class MaterialController {
         return Result.success(materialService.requestUploadToken(request, adminId, role));
     }
 
-    @ApiOperation("确认上传完成")
+    @ApiOperation(value = "确认上传完成", notes = "上传素材第二步：前端直传OSS完成后调用此接口创建素材记录，支持MD5去重\n\n**关联字典**：\n- material_tag：素材标签（上传时可选标签）")
     @PostMapping("/upload/confirm")
     public Result<MaterialVO> confirmUpload(
             @ApiParam("确认上传请求") @Valid @RequestBody MaterialUploadConfirmRequest request,
@@ -66,7 +66,7 @@ public class MaterialController {
         return Result.success(materialService.confirmUpload(request, adminId));
     }
 
-    @ApiOperation("文件夹上传初始化（创建分类+批量获取凭证）")
+    @ApiOperation(value = "文件夹上传初始化（创建分类+批量获取凭证）", notes = "支持整个文件夹上传：自动根据文件夹名创建子分类，为每个文件批量获取上传凭证，前端逐一上传后批量确认")
     @PostMapping("/upload/folder")
     public Result<FolderUploadInitVO> folderUploadInit(
             @ApiParam("文件夹上传初始化请求") @Valid @RequestBody FolderUploadInitRequest request,
@@ -79,7 +79,8 @@ public class MaterialController {
 
     // ==================== Chunk Upload (分片上传) ====================
 
-    @ApiOperation("分片上传-初始化")
+    @ApiOperation(value = "分片上传-初始化",
+            notes = "大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用完成合并接口。\n\n**权限**：需管理员登录，受角色分类权限限制。")
     @PostMapping("/upload/chunk/init")
     public Result<ChunkUploadInitVO> chunkUploadInit(
             @ApiParam("分片上传初始化请求") @Valid @RequestBody ChunkUploadInitRequest request,
@@ -89,7 +90,8 @@ public class MaterialController {
         return Result.success(chunkUploadService.initChunkUpload(request, adminId, role));
     }
 
-    @ApiOperation("分片上传-上传分片")
+    @ApiOperation(value = "分片上传-上传分片",
+            notes = "大文件上传第二步：逐个上传分片数据，分片索引从0开始。支持断点续传，已上传的分片无需重传。")
     @PostMapping("/upload/chunk")
     public Result<ChunkUploadPartVO> chunkUploadPart(
             @ApiParam("上传ID") @RequestParam("uploadId") String uploadId,
@@ -99,7 +101,8 @@ public class MaterialController {
         return Result.success(chunkUploadService.uploadChunk(uploadId, chunkIndex, chunk));
     }
 
-    @ApiOperation("分片上传-完成合并")
+    @ApiOperation(value = "分片上传-完成合并",
+            notes = "大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建素材记录。")
     @PostMapping("/upload/chunk/complete")
     public Result<MaterialVO> chunkUploadComplete(
             @ApiParam("分片上传完成请求") @Valid @RequestBody ChunkUploadCompleteRequest request,
@@ -108,7 +111,8 @@ public class MaterialController {
         return Result.success(chunkUploadService.completeChunkUpload(request.getUploadId(), adminId));
     }
 
-    @ApiOperation("分片上传-取消")
+    @ApiOperation(value = "分片上传-取消",
+            notes = "取消分片上传任务，清理已上传的分片数据和OSS临时文件。仅上传发起者可取消。")
     @PostMapping("/upload/chunk/cancel")
     public Result<Void> chunkUploadCancel(
             @ApiParam("分片上传取消请求") @Valid @RequestBody ChunkUploadCancelRequest request,
@@ -120,7 +124,7 @@ public class MaterialController {
 
     // ==================== CRUD ====================
 
-    @ApiOperation("素材列表")
+    @ApiOperation(value = "素材列表", notes = "分页查询素材，支持按分类、标签、文件类型、关键词筛选。返回结果受角色分类权限限制\n\n**关联字典**：\n- file_type：文件类型（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<MaterialVO>> listMaterials(
             @ApiParam("素材查询条件") @Valid MaterialQueryRequest query,
@@ -131,7 +135,8 @@ public class MaterialController {
         return Result.success(materialService.listMaterials(query, adminId, role, categoryMap));
     }
 
-    @ApiOperation("素材详情")
+    @ApiOperation(value = "素材详情",
+            notes = "返回素材完整信息，包含文件名、URL、分类、标签、文件大小、上传者等。受角色分类权限限制。\n\n**关联字典**：\n- file_type：文件类型（显示）")
     @GetMapping("/{materialId}")
     public Result<MaterialVO> getMaterial(
             @ApiParam("素材ID") @PathVariable Long materialId,
@@ -141,7 +146,7 @@ public class MaterialController {
         return Result.success(materialService.getMaterial(materialId, role, categoryMap));
     }
 
-    @ApiOperation("更新素材信息")
+    @ApiOperation(value = "更新素材信息", notes = "**关联字典**：\n- material_tag：素材标签（编辑时选择标签）")
     @PutMapping("/{materialId}")
     public Result<MaterialVO> updateMaterial(
             @ApiParam("素材ID") @PathVariable Long materialId,
@@ -153,7 +158,7 @@ public class MaterialController {
         return Result.success(materialService.updateMaterial(materialId, request, adminId, role, categoryMap));
     }
 
-    @ApiOperation("删除素材")
+    @ApiOperation(value = "删除素材", notes = "删除素材记录。如果素材存在引用关系（被景区、酒店等使用），则不允许删除")
     @DeleteMapping("/{materialId}")
     public Result<Void> deleteMaterial(
             @ApiParam("素材ID") @PathVariable Long materialId,
@@ -164,7 +169,7 @@ public class MaterialController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除素材")
+    @ApiOperation(value = "批量删除素材", notes = "批量删除素材，返回删除结果（成功数/失败数/失败原因）。有引用关系的素材会跳过并记录失败原因")
     @DeleteMapping("/batch")
     public Result<BatchDeleteResultVO> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,
@@ -179,7 +184,7 @@ public class MaterialController {
 
     // ==================== Tags on Materials ====================
 
-    @ApiOperation("更新素材标签")
+    @ApiOperation(value = "更新素材标签", notes = "全量替换单个素材的标签，传入新的标签ID列表")
     @PutMapping("/{materialId}/tags")
     public Result<Void> updateMaterialTags(
             @ApiParam("素材ID") @PathVariable Long materialId,
@@ -192,7 +197,7 @@ public class MaterialController {
         return Result.success();
     }
 
-    @ApiOperation("批量更新标签")
+    @ApiOperation(value = "批量更新标签", notes = "对多个素材同时添加和/或移除标签，支持增量操作（addTagIds新增，removeTagIds移除）")
     @PutMapping("/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签更新请求") @Valid @RequestBody BatchTagRequest request,
@@ -212,7 +217,7 @@ public class MaterialController {
 
     // ==================== References ====================
 
-    @ApiOperation("查看素材引用记录")
+    @ApiOperation(value = "查看素材引用记录", notes = "查看素材被哪些业务实体引用（如景区封面、酒店轮播图等），用于判断素材是否可安全删除")
     @GetMapping("/{materialId}/refs")
     public Result<List<MaterialRefVO>> getMaterialRefs(@ApiParam("素材ID") @PathVariable Long materialId) {
         return Result.success(refService.getRefsByMaterialId(materialId));
@@ -220,7 +225,7 @@ public class MaterialController {
 
     // ==================== Categories ====================
 
-    @ApiOperation("获取有权限的分类列表（含素材数量）")
+    @ApiOperation(value = "获取有权限的分类列表（含素材数量）", notes = "返回当前角色有权限查看的素材分类树，每个分类包含素材数量统计。超级管理员可见全部分类")
     @GetMapping("/categories")
     public Result<List<CategoryVO>> getCategories(HttpServletRequest httpRequest) {
         String role = getRole(httpRequest);
@@ -230,7 +235,7 @@ public class MaterialController {
 
     // ==================== Sub-categories ====================
 
-    @ApiOperation("创建子分类")
+    @ApiOperation(value = "创建子分类", notes = "在一级分类下创建子分类，分类编码自动生成。子分类用于更细粒度的素材归档")
     @PostMapping("/category/sub")
     public Result<CategoryVO> createSubCategory(
             @ApiParam("子分类创建请求") @Valid @RequestBody SubCategoryCreateRequest request,
@@ -241,7 +246,8 @@ public class MaterialController {
         return Result.success(categoryService.createSubCategory(request, adminId, role, categoryMap));
     }
 
-    @ApiOperation("更新子分类")
+    @ApiOperation(value = "更新子分类",
+            notes = "更新子分类的名称或排序值。仅有该分类权限的管理员可操作。")
     @PutMapping("/category/sub/{categoryId}")
     public Result<CategoryVO> updateSubCategory(
             @ApiParam("子分类ID") @PathVariable Long categoryId,
@@ -252,7 +258,7 @@ public class MaterialController {
         return Result.success(categoryService.updateSubCategory(categoryId, request, adminId, role));
     }
 
-    @ApiOperation("删除子分类")
+    @ApiOperation(value = "删除子分类", notes = "删除子分类前需确保分类下无素材，否则删除失败")
     @DeleteMapping("/category/sub/{categoryId}")
     public Result<Void> deleteSubCategory(
             @ApiParam("子分类ID") @PathVariable Long categoryId,

`hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java` (M)

接口变更 diff：

diff --git a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java
index a90884f..31d53b5 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java
@@ -23,19 +23,22 @@ public class MaterialTagController {
 
     private final MaterialTagService tagService;
 
-    @ApiOperation("获取管理标签（标签管理用）")
+    @ApiOperation(value = "获取管理标签（标签管理用）",
+            notes = "返回管理员创建的系统标签列表（不含用户自定义标签），用于标签管理页的CRUD操作。")
     @GetMapping("/tags")
     public Result<List<MaterialTagVO>> listManagedTags() {
         return Result.success(tagService.listManagedTags());
     }
 
-    @ApiOperation("获取全部标签（选择器用，含自定义标签）")
+    @ApiOperation(value = "获取全部标签（选择器用，含自定义标签）",
+            notes = "返回所有标签（含系统标签和用户自定义标签），用于素材上传/编辑时的标签选择器。")
     @GetMapping("/tags/all")
     public Result<List<MaterialTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建管理标签")
+    @ApiOperation(value = "创建管理标签",
+            notes = "创建系统级素材标签，标签名称不可重复。创建后可用于素材分类和筛选。\n\n**权限**：需管理员登录。")
     @PostMapping("/tag")
     public Result<MaterialTagVO> createTag(
             @ApiParam("创建标签请求") @Valid @RequestBody TagCreateRequest request,
@@ -44,7 +47,8 @@ public class MaterialTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签（按名称查找或创建）")
+    @ApiOperation(value = "解析自定义标签（按名称查找或创建）",
+            notes = "按标签名称查找已有标签，不存在则自动创建为用户自定义标签。用于素材上传时输入自由标签文本的场景。\n\n**权限**：需管理员登录。")
     @PostMapping("/tag/adhoc")
     public Result<MaterialTagVO> resolveAdHocTag(
             @ApiParam("自定义标签请求") @RequestBody TagCreateRequest request,
@@ -53,7 +57,8 @@ public class MaterialTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("编辑标签")
+    @ApiOperation(value = "编辑标签",
+            notes = "更新标签名称。标签名称不可与其他已有标签重复。\n\n**权限**：需管理员登录。")
     @PutMapping("/tag/{tagId}")
     public Result<MaterialTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -61,7 +66,8 @@ public class MaterialTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签",
+            notes = "删除标签并自动解除与所有素材的关联关系。\n\n**权限**：需管理员登录。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);

`hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java` (M)

接口变更 diff：

diff --git a/hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java b/hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java
index a595577..17f64ac 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java
@@ -20,7 +20,7 @@ public class MpMaterialController {
 
     private final MaterialService materialService;
 
-    @ApiOperation("获取小程序分类下的全部素材")
+    @ApiOperation(value = "获取小程序分类下的全部素材", notes = "返回miniprogram分类下的所有素材，用于小程序端展示公共素材资源（如引导页图片、默认头像等）")
     @GetMapping("/miniprogram")
     public Result<List<MaterialVO>> listMiniprogramMaterials() {
         return Result.success(materialService.listMaterialsByCategoryCode("miniprogram"));

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java
index 6c26fc1..04d1ebd 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java
@@ -19,7 +19,7 @@ public class ApprovalLogController {
 
     private final ApprovalLogService approvalLogService;
 
-    @ApiOperation("审批日志分页查询")
+    @ApiOperation(value = "审批日志分页查询", notes = "查询企微OA审批流程记录，支持按审批状态(1-审批中/2-已通过/3-已驳回/4-已撤销)、申请人、模板名称筛选\n\n**关联字典**：\n- approval_sp_status：审批状态（列表筛选+显示）")
     @GetMapping
     public Result<PageResult<ApprovalLog>> list(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -32,7 +32,7 @@ public class ApprovalLogController {
         return Result.success(approvalLogService.queryPage(page, pageSize, spStatus, applyUserName, spName, startTime, endTime));
     }
 
-    @ApiOperation("审批日志详情")
+    @ApiOperation(value = "审批日志详情", notes = "**关联字典**：\n- approval_sp_status：审批状态（显示）")
     @GetMapping("/{id}")
     public Result<ApprovalLog> detail(@ApiParam("日志ID") @PathVariable Long id) {
         ApprovalLog approvalLog = approvalLogService.getById(id);

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java
index 43d56d8..12117da 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java
@@ -19,7 +19,7 @@ public class DataRetentionController {
 
     private final DataRetentionService dataRetentionService;
 
-    @ApiOperation("手动触发数据清理")
+    @ApiOperation(value = "手动触发数据清理", notes = "仅超级管理员可操作。按数据保留策略清理过期日志（操作日志/错误日志/通知日志等），返回各类型清理的记录数")
     @PostMapping("/cleanup")
     public Result<Map<String, Integer>> cleanup(HttpServletRequest request) {
         requireSuperAdmin(request);

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java
index 77046be..06bbdf5 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java
@@ -19,7 +19,7 @@ public class ErrorLogController {
 
     private final ErrorLogService errorLogService;
 
-    @ApiOperation("错误日志分页查询")
+    @ApiOperation(value = "错误日志分页查询", notes = "查询各微服务的异常记录，支持按服务名称、异常类名、时间范围筛选。堆栈信息仅保留com.hulalv包内的调用帧")
     @GetMapping
     public Result<PageResult<ErrorLog>> list(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -31,7 +31,8 @@ public class ErrorLogController {
         return Result.success(errorLogService.queryPage(page, pageSize, serviceName, exceptionClass, startTime, endTime));
     }
 
-    @ApiOperation("错误日志详情")
+    @ApiOperation(value = "错误日志详情",
+            notes = "返回单条错误日志的完整信息，包含异常类名、错误消息、过滤后的堆栈信息（仅com.hulalv包内调用帧）、请求URL、请求参数等。")
     @GetMapping("/{id}")
     public Result<ErrorLog> detail(@ApiParam("日志ID") @PathVariable Long id) {
         ErrorLog errorLog = errorLogService.getById(id);

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java
index 51e3999..44d463e 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java
@@ -18,7 +18,7 @@ import org.springframework.web.bind.annotation.*;
  * Internal endpoints for receiving logs from other services.
  * NOT exposed via gateway.
  */
-@Api(tags = "【内部接口】日志接收（Feign调用）")
+@Api(tags = "【内部接口】日志接收（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/monitor")
 @RequiredArgsConstructor
@@ -29,35 +29,35 @@ public class InternalLogController {
     private final NotificationLogService notificationLogService;
     private final ApprovalLogService approvalLogService;
 
-    @ApiOperation("Receive operation log")
+    @ApiOperation(value = "接收操作日志", notes = "各微服务通过AOP拦截@OperationLog注解的方法，异步发送操作日志到此接口存储")
     @PostMapping("/operation-log")
-    public Result<?> receiveOperationLog(@RequestBody OperationLogDTO dto) {
+    public Result<Void> receiveOperationLog(@RequestBody OperationLogDTO dto) {
         operationLogService.saveFromDTO(dto);
         return Result.success();
     }
 
-    @ApiOperation("Receive error log")
+    @ApiOperation(value = "接收错误日志", notes = "各微服务的GlobalExceptionHandler捕获异常后，异步发送错误日志到此接口存储")
     @PostMapping("/error-log")
-    public Result<?> receiveErrorLog(@RequestBody ErrorLogDTO dto) {
+    public Result<Void> receiveErrorLog(@RequestBody ErrorLogDTO dto) {
         errorLogService.saveFromDTO(dto);
         return Result.success();
     }
 
-    @ApiOperation("Receive notification log")
+    @ApiOperation(value = "接收通知日志", notes = "通知服务发送消息（短信/站内信/企微等）后，记录发送结果到此接口")
     @PostMapping("/notification-log")
-    public Result<?> receiveNotificationLog(@RequestBody NotificationLogDTO dto) {
+    public Result<Void> receiveNotificationLog(@RequestBody NotificationLogDTO dto) {
         notificationLogService.saveFromDTO(dto);
         return Result.success();
     }
 
-    @ApiOperation("Receive approval log")
+    @ApiOperation(value = "接收审批日志", notes = "企微回调服务接收审批事件后，发送审批日志到此接口。同一审批单号会更新已有记录（按thirdNo去重）")
     @PostMapping("/approval-log")
-    public Result<?> receiveApprovalLog(@RequestBody ApprovalLogDTO dto) {
+    public Result<Void> receiveApprovalLog(@RequestBody ApprovalLogDTO dto) {
         approvalLogService.saveOrUpdateByThirdNo(dto);
         return Result.success();
     }
 
-    @ApiOperation("Get customer stats for a user (add/loss counts)")
+    @ApiOperation(value = "获取用户客户统计", notes = "统计指定用户的客户增减数据（新增客户数/流失客户数），用于客户管理看板")
     @GetMapping("/notification-log/customer-stats")
     public Result<java.util.Map<String, Object>> getCustomerStats(
             @RequestParam("userId") String userId) {

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java
index 52c9e86..bc58580 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java
@@ -19,7 +19,7 @@ public class LoginLogController {
 
     private final UserServiceClient userServiceClient;
 
-    @ApiOperation("登录日志分页查询")
+    @ApiOperation(value = "登录日志分页查询", notes = "查询管理员登录记录（代理到user-service），包含登录IP、设备信息、登录方式和登录结果\n\n**关联字典**：\n- login_status：登录状态（列表筛选+显示）")
     @GetMapping
     public Result<?> list(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java
index 029e317..0d29b88 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java
@@ -21,20 +21,20 @@ public class MysqlMonitorController {
 
     private final MysqlMonitorService mysqlMonitorService;
 
-    @ApiOperation("MySQL实时监控数据")
+    @ApiOperation(value = "MySQL实时监控数据", notes = "返回MySQL实时状态：连接数、QPS、缓冲池命中率、线程状态、慢查询计数等核心指标")
     @GetMapping
     public Result<Map<String, Object>> overview() {
         return Result.success(mysqlMonitorService.getOverview());
     }
 
-    @ApiOperation("表空间列表")
+    @ApiOperation(value = "表空间列表", notes = "查询各数据库表的空间占用情况，包含数据大小、索引大小、行数等信息。可指定schema筛选，仅允许查询hl_前缀的数据库")
     @GetMapping("/tables")
     public Result<List<Map<String, Object>>> tables(
             @ApiParam("数据库名") @RequestParam(required = false) String schema) {
         return Result.success(mysqlMonitorService.getTableSpaces(schema));
     }
 
-    @ApiOperation("慢SQL查询统计")
+    @ApiOperation(value = "慢SQL查询统计", notes = "仅超级管理员可操作。查询慢SQL统计信息，返回执行时间最长的SQL语句及其执行次数、平均耗时等")
     @GetMapping("/slow-queries")
     public Result<List<Map<String, Object>>> slowQueries(
             HttpServletRequest request,

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java
index 7e55cae..46d7b72 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java
@@ -19,7 +19,7 @@ public class NotificationLogController {
 
     private final NotificationLogService notificationLogService;
 
-    @ApiOperation("消息通知日志分页查询")
+    @ApiOperation(value = "消息通知日志分页查询", notes = "查询各渠道（短信/站内信/企微/公众号）的通知发送记录，支持按通知类型、用户、发送状态筛选\n\n**关联字典**：\n- notification_send_status：发送状态（列表筛选+显示，0=待发送/1=成功/2=失败）")
     @GetMapping
     public Result<PageResult<NotificationLog>> list(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -32,7 +32,8 @@ public class NotificationLogController {
         return Result.success(notificationLogService.queryPage(page, pageSize, notificationType, userName, sendStatus, startTime, endTime));
     }
 
-    @ApiOperation("消息通知日志详情")
+    @ApiOperation(value = "消息通知日志详情",
+            notes = "返回单条通知发送日志的完整信息，包含通知类型、接收用户、发送渠道、发送状态、失败原因（如有）、消息内容等。")
     @GetMapping("/{id}")
     public Result<NotificationLog> detail(@ApiParam("日志ID") @PathVariable Long id) {
         NotificationLog notificationLog = notificationLogService.getById(id);

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java
index 43516e4..f620a50 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java
@@ -19,7 +19,7 @@ public class OperationLogController {
 
     private final OperationLogService operationLogService;
 
-    @ApiOperation("操作日志分页查询")
+    @ApiOperation(value = "操作日志分页查询", notes = "查询管理员的操作记录，支持按模块、管理员、状态、时间范围筛选。记录包含请求参数、响应结果和耗时信息\n\n**关联字典**：\n- operation_log_status：操作状态（列表筛选+显示，0=成功/1=失败）")
     @GetMapping
     public Result<PageResult<OperationLog>> list(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -32,7 +32,8 @@ public class OperationLogController {
         return Result.success(operationLogService.queryPage(page, pageSize, module, adminId, status, startTime, endTime));
     }
 
-    @ApiOperation("操作日志详情")
+    @ApiOperation(value = "操作日志详情",
+            notes = "返回单条操作日志的完整信息，包含操作模块、操作描述、请求参数、响应结果、操作耗时、操作人信息、IP地址等。")
     @GetMapping("/{id}")
     public Result<OperationLog> detail(@ApiParam("日志ID") @PathVariable Long id) {
         OperationLog log = operationLogService.getById(id);

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java
index e70ae11..ffc059f 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java
@@ -17,7 +17,7 @@ public class RedisMonitorController {
 
     private final RedisMonitorService redisMonitorService;
 
-    @ApiOperation("Redis实时监控数据")
+    @ApiOperation(value = "Redis实时监控数据", notes = "返回Redis实时状态：内存使用量、连接数、Key数量、命中率、每秒命令数等核心指标")
     @GetMapping
     public Result<Map<String, Object>> overview() {
         return Result.success(redisMonitorService.getOverview());

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java
index 5d642cb..9f32297 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java
@@ -18,19 +18,19 @@ public class RocketMqMonitorController {
 
     private final RocketMqMonitorService rocketMqMonitorService;
 
-    @ApiOperation("RocketMQ概览")
+    @ApiOperation(value = "RocketMQ概览", notes = "返回RocketMQ集群状态：Broker状态、Topic数量、消息积压量、生产者/消费者连接数等核心指标")
     @GetMapping
     public Result<Map<String, Object>> overview() {
         return Result.success(rocketMqMonitorService.getOverview());
     }
 
-    @ApiOperation("Topic统计")
+    @ApiOperation(value = "Topic统计", notes = "返回各Topic的消息量、最新偏移量和消费进度等信息")
     @GetMapping("/topics")
     public Result<List<Map<String, Object>>> topicStats() {
         return Result.success(rocketMqMonitorService.getTopicStats());
     }
 
-    @ApiOperation("消费者组统计")
+    @ApiOperation(value = "消费者组统计", notes = "返回各消费者组的消费进度、积压量和在线消费者实例信息")
     @GetMapping("/consumer-groups")
     public Result<List<Map<String, Object>>> consumerGroupStats() {
         return Result.success(rocketMqMonitorService.getConsumerGroupStats());

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java` (M)

接口变更 diff：

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java
index 63d09ef..11e5509 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java
@@ -18,7 +18,7 @@ public class ServiceMonitorController {
 
     private final ServiceMonitorService serviceMonitorService;
 
-    @ApiOperation("微服务列表和健康状态")
+    @ApiOperation(value = "微服务列表和健康状态", notes = "从Nacos注册中心获取所有微服务的实例列表和健康状态，包含IP、端口、注册时间和健康检查结果")
     @GetMapping
     public Result<List<Map<String, Object>>> list() {
         return Result.success(serviceMonitorService.getServiceList());

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java
index f7f787c..da96036 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java
@@ -22,7 +22,8 @@ public class MpActivityController {
     private final MpResourceFeignClient resourceFeignClient;
     private final ResourceMapService resourceMapService;
 
-    @ApiOperation("活动列表")
+    @ApiOperation(value = "活动列表",
+            notes = "分页查询已上架的活动列表，支持关键词和分类筛选。聚合层透传resource-service的活动数据给小程序前端。")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listActivities(
             @ApiParam("关键词") @RequestParam(required = false) String keyword,
@@ -37,7 +38,8 @@ public class MpActivityController {
         return resourceFeignClient.listActivities(query);
     }
 
-    @ApiOperation("活动详情")
+    @ApiOperation(value = "活动详情",
+            notes = "获取活动完整信息（含图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。")
     @GetMapping("/{activityId}")
     public Result<Map<String, Object>> getActivityDetail(@ApiParam("活动ID") @PathVariable Long activityId) {
         Result<Map<String, Object>> result = resourceFeignClient.getActivityDetail(activityId);

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java
index 9023792..61ad359 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java
@@ -18,7 +18,7 @@ public class MpBadgeController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("获取徽章数据")
+    @ApiOperation(value = "获取徽章数据", notes = "返回用户的徽章统计（未读消息数、待办事项数等），用于「我的」页面角标展示")
     @GetMapping
     public Result<Map<String, Object>> getBadges(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java
index 6089f32..df4d3dd 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java
@@ -23,7 +23,8 @@ public class MpBannerController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("获取当前生效的轮播图列表")
+    @ApiOperation(value = "获取当前生效的轮播图列表",
+            notes = "返回当前处于有效期内的轮播图，按排序值排列。用于小程序首页顶部轮播展示，透传自user-service。")
     @GetMapping("/active")
     public Result<List<Map<String, Object>>> listActiveBanners() {
         return userFeignClient.listActiveBanners();

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java
index be29a79..84ec777 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java
@@ -22,13 +22,15 @@ public class MpConfigController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("获取所有非敏感前端配置")
+    @ApiOperation(value = "获取所有非敏感前端配置",
+            notes = "返回所有非SECRET类型的前端配置项（如主题色、客服电话、版本号等）。不含敏感配置，可安全传输给小程序端。")
     @GetMapping
     public Result<List<Map<String, Object>>> listPublicConfigs() {
         return userFeignClient.listAllFrontendConfigs();
     }
 
-    @ApiOperation("按分组获取非敏感前端配置")
+    @ApiOperation(value = "按分组获取非敏感前端配置",
+            notes = "按配置分组获取前端配置项，如UI分组、功能开关分组等。用于小程序按需加载特定分组的配置。")
     @GetMapping("/group/{group}")
     public Result<List<Map<String, Object>>> listPublicConfigsByGroup(
             @ApiParam("配置分组") @PathVariable String group) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java
index 4e34f66..c5b60cb 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java
@@ -20,7 +20,7 @@ public class MpContractController {
 
     private final MpContractFeignClient contractFeignClient;
 
-    @ApiOperation("合同列表")
+    @ApiOperation(value = "合同列表", notes = "**关联字典（BFF透传）**：\n- contract_status：合同状态（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listContracts(
             HttpServletRequest request,
@@ -31,7 +31,7 @@ public class MpContractController {
         return contractFeignClient.listContracts(userId, status, page, pageSize);
     }
 
-    @ApiOperation(value = "合同详情", notes = "返回合同基本信息、签署状态、出行人签署详情及合同文件下载链接")
+    @ApiOperation(value = "合同详情", notes = "返回合同基本信息、签署状态、出行人签署详情及合同文件下载链接\n\n**关联字典（BFF透传）**：\n- contract_status：合同状态（显示）")
     @GetMapping("/{id}")
     public Result<Map<String, Object>> getContractDetail(
             HttpServletRequest request,
@@ -40,7 +40,7 @@ public class MpContractController {
         return contractFeignClient.getContractDetail(id, userId);
     }
 
-    @ApiOperation(value = "按订单查合同", notes = "返回订单关联的最新有效合同（非作废）")
+    @ApiOperation(value = "按订单查合同", notes = "返回订单关联的最新有效合同（非作废）\n\n**关联字典（BFF透传）**：\n- contract_status：合同状态（显示）")
     @GetMapping("/by-order/{orderId}")
     public Result<Map<String, Object>> getContractByOrder(
             HttpServletRequest request,
@@ -49,7 +49,7 @@ public class MpContractController {
         return contractFeignClient.getContractByOrder(orderId, userId);
     }
 
-    @ApiOperation(value = "按订单查所有合同", notes = "返回订单关联的所有有效合同（TOUR+INSURANCE各一条）")
+    @ApiOperation(value = "按订单查所有合同", notes = "返回订单关联的所有有效合同（TOUR+INSURANCE各一条）\n\n**关联字典（BFF透传）**：\n- contract_status：合同状态（显示）")
     @GetMapping("/by-order/{orderId}/all")
     public Result<java.util.List<Map<String, Object>>> getContractsByOrder(
             HttpServletRequest request,
@@ -58,7 +58,8 @@ public class MpContractController {
         return contractFeignClient.getContractsByOrder(orderId, userId);
     }
 
-    @ApiOperation("重新发送合同签署短信")
+    @ApiOperation(value = "重新发送合同签署短信",
+            notes = "重新向出行人发送合同签署短信通知，适用于出行人未收到短信或短信过期的场景。\n\n**权限**：需登录。")
     @PostMapping("/{contractId}/resend-sms")
     public Result<Boolean> resendContractSms(
             @ApiParam("合同ID") @PathVariable Long contractId,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java
index ae62fb8..01d0115 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java
@@ -22,7 +22,8 @@ public class MpDesignerController {
     private final MpUserFeignClient userFeignClient;
     private final DesignerAggregationService designerAggregationService;
 
-    @ApiOperation("定制师列表(含真实产品数和评分，综合排序)")
+    @ApiOperation(value = "定制师列表(含真实产品数和评分，综合排序)",
+            notes = "获取定制师列表，聚合层会补充每个定制师的真实产品数量和评价评分。按综合排序（评分>路线数>咨询人数），用于小程序定制师推荐页。")
     @SuppressWarnings("unchecked")
     @GetMapping
     public Result<List<Map<String, Object>>> listDesigners(
@@ -37,7 +38,8 @@ public class MpDesignerController {
         return result;
     }
 
-    @ApiOperation("推荐定制师(综合排序第一名)")
+    @ApiOperation(value = "推荐定制师(综合排序第一名)",
+            notes = "获取综合排序排名第一的定制师信息（含产品数和评分），用于首页推荐定制师卡片展示。")
     @GetMapping("/featured")
     public Result<Map<String, Object>> getFeaturedDesigner() {
         // Fetch all designers, enrich and sort, return top one
@@ -74,7 +76,8 @@ public class MpDesignerController {
         try { return Integer.parseInt(obj.toString()); } catch (NumberFormatException e) { return 0; }
     }
 
-    @ApiOperation("定制师详情(含产品数量和评分)")
+    @ApiOperation(value = "定制师详情(含产品数量和评分)",
+            notes = "获取定制师完整个人信息，聚合层会补充该定制师的已发布产品数量和综合评分，用于定制师个人主页展示。")
     @GetMapping("/{id}")
     public Result<Map<String, Object>> getDesignerDetail(@ApiParam("定制师ID") @PathVariable Long id) {
         Map<String, Object> data = designerAggregationService.getDesignerDetailWithStats(id);
@@ -84,7 +87,7 @@ public class MpDesignerController {
         return Result.success(data);
     }
 
-    @ApiOperation("定制师已发布产品列表")
+    @ApiOperation(value = "定制师已发布产品列表", notes = "**关联字典（BFF透传）**：\n- product_type：产品类型（显示）")
     @GetMapping("/{id}/products")
     public Result<PageResult<Map<String, Object>>> getDesignerProducts(
             @ApiParam("定制师ID") @PathVariable Long id,
@@ -93,7 +96,7 @@ public class MpDesignerController {
         return designerAggregationService.getDesignerProducts(id, page, pageSize);
     }
 
-    @ApiOperation("定制师产品评价列表")
+    @ApiOperation(value = "定制师产品评价列表", notes = "**关联字典（BFF透传）**：\n- rating_level：评价等级（显示）")
     @GetMapping("/{id}/reviews")
     public Result<PageResult<Map<String, Object>>> getDesignerReviews(
             @ApiParam("定制师ID") @PathVariable Long id,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java
index b57cfd7..e689361 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java
@@ -23,7 +23,7 @@ public class MpDictController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("获取所有字典数据")
+    @ApiOperation(value = "获取所有字典数据", notes = "获取系统全部字典数据（按字典类型分组），用于小程序端的下拉选项、枚举映射等。建议前端缓存此数据")
     @GetMapping("/all")
     public Result<List<Map<String, Object>>> getAllDict() {
         return userFeignClient.getAllDict();

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java
index ba1fcaa..5aa4cfc 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java
@@ -9,6 +9,7 @@ import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import javax.servlet.http.HttpServletRequest;
+import java.util.Map;
 
 @Api(tags = "C端 - 探索接口")
 @RestController
@@ -18,9 +19,10 @@ public class MpExploreController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("探索列表")
+    @ApiOperation(value = "探索列表",
+            notes = "获取已启用的探索分类列表（图文攻略内容），支持综合/最新/最热排序，分页返回。用于小程序探索频道首页瀑布流展示。")
     @GetMapping("/list")
-    public Result<?> list(
+    public Result<Map<String, Object>> list(
             @ApiParam("排序方式：comprehensive/newest/hottest") @RequestParam(defaultValue = "comprehensive") String sortType,
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
             @ApiParam("每页条数") @RequestParam(defaultValue = "20") int pageSize) {
@@ -29,7 +31,7 @@ public class MpExploreController {
 
     @ApiOperation(value = "探索详情", notes = "自动增加浏览量，已登录时返回点赞/收藏状态")
     @GetMapping("/{id}")
-    public Result<?> detail(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
+    public Result<Map<String, Object>> detail(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
         // optional auth: userId may be null if not logged in
         Long userId = null;
         String userIdHeader = request.getHeader("X-User-Id");
@@ -42,22 +44,25 @@ public class MpExploreController {
         return userFeignClient.getExploreCategoryDetail(id, userId);
     }
 
-    @ApiOperation("浏览+1")
+    @ApiOperation(value = "浏览+1",
+            notes = "增加探索内容的浏览计数。前端进入探索详情页时调用，无需登录。")
     @PostMapping("/{id}/view")
-    public Result<?> view(@ApiParam("探索分类ID") @PathVariable Long id) {
+    public Result<Void> view(@ApiParam("探索分类ID") @PathVariable Long id) {
         return userFeignClient.incrementExploreViewCount(id);
     }
 
-    @ApiOperation("切换点赞")
+    @ApiOperation(value = "切换点赞",
+            notes = "对探索内容点赞/取消点赞，返回当前点赞状态（true=已点赞）。\n\n**权限**：需登录。")
     @PostMapping("/{id}/like")
-    public Result<?> toggleLike(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
+    public Result<Boolean> toggleLike(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.toggleExploreLike(id, userId);
     }
 
-    @ApiOperation("切换收藏")
+    @ApiOperation(value = "切换收藏",
+            notes = "对探索内容收藏/取消收藏，返回当前收藏状态（true=已收藏）。收藏后可在'我的收藏'中查看。\n\n**权限**：需登录。")
     @PostMapping("/{id}/favorite")
-    public Result<?> toggleFavorite(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
+    public Result<Boolean> toggleFavorite(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.toggleExploreFavorite(id, userId);
     }

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java
index 94c53e4..d596692 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java
@@ -27,7 +27,7 @@ public class MpFavoriteController {
     private final MpUserFeignClient userFeignClient;
     private final FavoriteAggregationService favoriteAggregationService;
 
-    @ApiOperation("添加收藏")
+    @ApiOperation(value = "添加收藏", notes = "将产品/景区/餐厅/活动加入收藏。同一目标重复收藏会返回已有收藏记录")
     @PostMapping
     public Result<Map<String, Object>> addFavorite(HttpServletRequest request,
                                                     @Valid @RequestBody MpFavoriteRequest body) {
@@ -38,7 +38,8 @@ public class MpFavoriteController {
         return userFeignClient.addFavorite(userId, map);
     }
 
-    @ApiOperation("收藏列表（含资源摘要）")
+    @ApiOperation(value = "收藏列表（含资源摘要）",
+            notes = "分页查询收藏列表，聚合层会补充每个收藏项对应资源的摘要信息（名称、封面图、价格等）。支持按目标类型筛选。\n\n**权限**：需登录。\n\n**关联字典**：\n- favorite_resource_type：收藏资源类型（PRODUCT/SCENIC/RESTAURANT/ACTIVITY）")
     @GetMapping
     public Result<PageResult<FavoriteItemVO>> listFavorites(HttpServletRequest request,
                                                             @ApiParam("目标类型筛选（字典：favorite_resource_type）：PRODUCT/SCENIC/RESTAURANT/ACTIVITY")
@@ -49,7 +50,8 @@ public class MpFavoriteController {
         return Result.success(favoriteAggregationService.listFavorites(userId, targetType, page, pageSize));
     }
 
-    @ApiOperation("检查是否已收藏")
+    @ApiOperation(value = "检查是否已收藏",
+            notes = "检查当前用户是否已收藏指定资源，用于详情页收藏按钮状态显示。\n\n**权限**：需登录。")
     @GetMapping("/check")
     public Result<Boolean> checkFavorite(HttpServletRequest request,
                                           @ApiParam("目标类型（字典：favorite_resource_type）") @RequestParam String targetType,
@@ -58,7 +60,8 @@ public class MpFavoriteController {
         return userFeignClient.checkFavorite(userId, targetType, targetId);
     }
 
-    @ApiOperation("批量删除收藏")
+    @ApiOperation(value = "批量删除收藏",
+            notes = "批量删除多条收藏记录，传入收藏记录ID列表。用于收藏管理页面的批量操作。\n\n**权限**：需登录，仅能删除自己的收藏。")
     @DeleteMapping("/batch")
     public Result<Void> batchDeleteFavorites(HttpServletRequest request,
                                               @ApiParam("收藏ID列表") @RequestBody List<Long> ids) {
@@ -66,7 +69,8 @@ public class MpFavoriteController {
         return userFeignClient.batchDeleteFavorites(userId, ids);
     }
 
-    @ApiOperation("按目标取消收藏")
+    @ApiOperation(value = "按目标取消收藏",
+            notes = "通过目标类型+目标ID取消收藏，适用于详情页点击取消收藏的场景（不需要知道收藏记录ID）。\n\n**权限**：需登录。")
     @DeleteMapping("/by-target")
     public Result<Void> deleteFavoriteByTarget(HttpServletRequest request,
                                                 @ApiParam("目标类型") @RequestParam String targetType,
@@ -75,7 +79,8 @@ public class MpFavoriteController {
         return userFeignClient.deleteFavoriteByTarget(userId, targetType, targetId);
     }
 
-    @ApiOperation("取消收藏")
+    @ApiOperation(value = "取消收藏",
+            notes = "通过收藏记录ID取消收藏，适用于收藏列表页的删除操作。\n\n**权限**：需登录，仅能删除自己的收藏。")
     @DeleteMapping("/{id}")
     public Result<Void> deleteFavorite(HttpServletRequest request,
                                         @ApiParam("收藏记录ID") @PathVariable Long id) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java
index c25ed9b..ab02f01 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java
@@ -26,7 +26,7 @@ public class MpFootprintController {
     private final MpUserFeignClient userFeignClient;
     private final FootprintAggregationService footprintAggregationService;
 
-    @ApiOperation("记录足迹")
+    @ApiOperation(value = "记录足迹", notes = "记录用户浏览资源的足迹，同一资源重复浏览会更新浏览时间而非新增记录")
     @PostMapping
     public Result<Map<String, Object>> addFootprint(HttpServletRequest request,
                                                      @RequestBody MpFootprintAddRequest body) {
@@ -37,7 +37,8 @@ public class MpFootprintController {
         return userFeignClient.addFootprint(userId, map);
     }
 
-    @ApiOperation("足迹列表（含资源摘要）")
+    @ApiOperation(value = "足迹列表（含资源摘要）",
+            notes = "分页查询浏览足迹列表，聚合层会补充每条足迹对应资源的摘要信息（名称、封面图等）。支持按资源类型筛选，按浏览时间倒序。\n\n**权限**：需登录。")
     @GetMapping
     public Result<PageResult<FootprintItemVO>> listFootprints(HttpServletRequest request,
                                                                @ApiParam("资源类型筛选：PRODUCT/SCENIC/RESTAURANT/ACTIVITY") @RequestParam(required = false) String resourceType,
@@ -47,14 +48,16 @@ public class MpFootprintController {
         return Result.success(footprintAggregationService.listFootprints(userId, resourceType, page, pageSize));
     }
 
-    @ApiOperation("删除足迹")
+    @ApiOperation(value = "删除足迹",
+            notes = "删除单条浏览足迹记录。\n\n**权限**：需登录，仅能删除自己的足迹。")
     @DeleteMapping("/{id}")
     public Result<Void> deleteFootprint(HttpServletRequest request, @ApiParam("足迹ID") @PathVariable Long id) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.deleteFootprint(userId, id);
     }
 
-    @ApiOperation("批量删除足迹")
+    @ApiOperation(value = "批量删除足迹",
+            notes = "批量删除多条浏览足迹记录，传入足迹ID列表。用于足迹管理页面的批量清理。\n\n**权限**：需登录，仅能删除自己的足迹。")
     @DeleteMapping("/batch")
     public Result<Void> batchDeleteFootprints(HttpServletRequest request,
                                                @ApiParam("足迹ID列表") @RequestBody List<Long> ids) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java
index 8e7cdc5..0c6487f 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java
@@ -18,7 +18,7 @@ public class MpHomeController {
 
     private final HomeAggregationService homeAggregationService;
 
-    @ApiOperation(value = "首页数据", notes = "聚合流程：并行获取推荐产品列表+产品线列表+轮播图 → Redis缓存5分钟 → 返回聚合数据")
+    @ApiOperation(value = "首页数据", notes = "聚合流程：并行获取推荐产品列表+产品线列表+轮播图 → Redis缓存5分钟 → 返回聚合数据\n\n**关联字典（BFF透传）**：\n- product_type：产品类型（产品卡片显示）\n- product_status：产品状态（透传自product-service）")
     @GetMapping
     public Result<HomeDataVO> getHomeData() {
         return Result.success(homeAggregationService.getHomeData());

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java
index d820bba..2d649e1 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java
@@ -22,7 +22,8 @@ public class MpHotelController {
     private final MpResourceFeignClient resourceFeignClient;
     private final ResourceMapService resourceMapService;
 
-    @ApiOperation("酒店列表")
+    @ApiOperation(value = "酒店列表",
+            notes = "分页查询已上架的酒店列表，支持按关键词、城市、星级筛选。聚合层透传resource-service的酒店数据。")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listHotels(
             @ApiParam("关键词") @RequestParam(required = false) String keyword,
@@ -39,7 +40,8 @@ public class MpHotelController {
         return resourceFeignClient.listHotels(query);
     }
 
-    @ApiOperation("酒店详情")
+    @ApiOperation(value = "酒店详情",
+            notes = "获取酒店完整信息（含房型列表、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。")
     @GetMapping("/{hotelId}")
     public Result<Map<String, Object>> getHotelDetail(@ApiParam("酒店ID") @PathVariable Long hotelId) {
         Result<Map<String, Object>> result = resourceFeignClient.getHotelDetail(hotelId);

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java
index 3941bc4..d1403a0 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java
@@ -18,7 +18,7 @@ public class MpInsuranceController {
 
     private final MpInsuranceFeignClient insuranceFeignClient;
 
-    @ApiOperation(value = "获取订单所有保单PDF", notes = "合并所有出行人的有效保单为一个PDF，返回base64")
+    @ApiOperation(value = "获取订单所有保单PDF", notes = "合并所有出行人的有效保单为一个PDF，返回base64\n\n**关联字典（BFF透传）**：\n- insurance_status：保险状态（返回字段）")
     @GetMapping("/policy-pdf/{orderId}")
     public Result<Map<String, Object>> getPolicyPdf(
             @ApiParam("订单ID") @PathVariable Long orderId) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java
index bda90ad..a42a662 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java
@@ -31,7 +31,7 @@ public class MpInvoiceController {
         return orderFeignClient.applyInvoice(userId, body);
     }
 
-    @ApiOperation("发票详情")
+    @ApiOperation(value = "发票详情", notes = "获取发票的完整信息，包含开票状态、发票抬头、税号、金额、电子发票文件链接等")
     @GetMapping("/{id}")
     public Result<Map<String, Object>> getInvoiceDetail(@ApiParam("发票ID") @PathVariable Long id,
                                                          HttpServletRequest request) {
@@ -39,7 +39,7 @@ public class MpInvoiceController {
         return orderFeignClient.getInvoiceDetail(id, userId);
     }
 
-    @ApiOperation("通过订单ID查询发票")
+    @ApiOperation(value = "通过订单ID查询发票", notes = "查询指定订单的发票信息，如果订单未开票则返回null")
     @GetMapping("/order/{orderId}")
     public Result<Map<String, Object>> getInvoiceByOrderId(@ApiParam("订单ID") @PathVariable Long orderId,
                                                             HttpServletRequest request) {
@@ -47,7 +47,7 @@ public class MpInvoiceController {
         return orderFeignClient.getInvoiceByOrderId(orderId, userId);
     }
 
-    @ApiOperation("发票换开")
+    @ApiOperation(value = "发票换开", notes = "对已开发票申请换开（修改抬头/税号等），原发票作废后重新开具新发票")
     @PostMapping("/{invoiceId}/reissue")
     public Result<Map<String, Object>> reissueInvoice(
             @ApiParam("发票ID") @PathVariable Long invoiceId,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java
index d60be9e..c8d50b5 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java
@@ -57,7 +57,8 @@ public class MpLikeController {
         return result;
     }
 
-    @ApiOperation("检查是否已点赞")
+    @ApiOperation(value = "检查是否已点赞",
+            notes = "检查当前用户是否已对指定目标点赞，用于前端点赞按钮状态展示。\n\n**权限**：需登录。")
     @GetMapping("/{targetType}/{targetId}/check")
     public Result<Boolean> checkLike(
             @ApiParam("目标类型") @PathVariable String targetType,
@@ -67,7 +68,8 @@ public class MpLikeController {
         return userFeignClient.checkLikeStatus(targetType.toUpperCase(), targetId, userId);
     }
 
-    @ApiOperation("批量检查点赞状态")
+    @ApiOperation(value = "批量检查点赞状态",
+            notes = "批量检查当前用户是否已对多个目标点赞，返回已点赞的目标ID列表。用于列表页批量展示点赞状态。\n\n**权限**：需登录。")
     @PostMapping("/{targetType}/batch-check")
     public Result<List<String>> batchCheckLiked(
             @ApiParam("目标类型") @PathVariable String targetType,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java
index bc4abe0..e1f7fa6 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java
@@ -37,7 +37,7 @@ public class MpOrderController {
         return orderFeignClient.createOrder(userId, body);
     }
 
-    @ApiOperation("订单列表")
+    @ApiOperation(value = "订单列表", notes = "分页查询当前用户的订单列表，支持按状态筛选。返回订单摘要信息（不含详细出行人信息）\n\n**关联字典（BFF透传）**：\n- order_status：订单状态（列表筛选+显示）\n- product_type：产品类型（订单卡片显示）")
     @GetMapping("/list")
     public Result<PageResult<MpOrderListItemVO>> listOrders(HttpServletRequest request,
                                                               @ApiParam("状态") @RequestParam(required = false) String status,
@@ -51,7 +51,7 @@ public class MpOrderController {
         return orderFeignClient.listOrders(userId, query);
     }
 
-    @ApiOperation("订单详情")
+    @ApiOperation(value = "订单详情", notes = "获取订单完整信息，包含产品快照、出行人列表、支付信息、合同状态等\n\n**关联字典（BFF透传）**：\n- order_status：订单状态（显示）\n- product_type：产品类型（显示）\n- contract_status：合同状态（显示）")
     @GetMapping("/{orderId}")
     public Result<MpOrderDetailVO> getOrder(HttpServletRequest request,
                                               @ApiParam("订单ID") @PathVariable Long orderId) {
@@ -86,9 +86,10 @@ public class MpOrderController {
         return orderFeignClient.cancelOrder(userId, orderId, body != null ? body : new MpCancelOrderRequest());
     }
 
-    @ApiOperation("通过联系人手机号+姓名查找订单（无需登录）")
+    @ApiOperation(value = "通过联系人手机号+姓名查找订单（无需登录）",
+            notes = "无需登录即可查询。用于管理员代下单场景：管理员创建订单后，用户通过联系人手机号+姓名查找订单并绑定到自己账号。仅返回尚未绑定用户(userId=NULL)的订单。")
     @GetMapping("/lookup")
-    public Result<?> lookupByContact(@ApiParam("联系人手机号") @RequestParam String contactPhone,
+    public Result<List<Map<String, Object>>> lookupByContact(@ApiParam("联系人手机号") @RequestParam String contactPhone,
                                      @ApiParam("联系人姓名") @RequestParam String contactName) {
         return orderFeignClient.lookupByContact(contactPhone, contactName);
     }
@@ -101,7 +102,7 @@ public class MpOrderController {
         return orderFeignClient.bindByContact(userId, body);
     }
 
-    @ApiOperation("同意解锁订单")
+    @ApiOperation(value = "同意解锁订单", notes = "用户同意管理员的修改请求，解除订单锁定状态，允许管理员继续修改订单")
     @PostMapping("/{orderId}/approve-unlock")
     public Result<Void> approveUnlock(HttpServletRequest request,
                                        @ApiParam("订单ID") @PathVariable Long orderId) {
@@ -116,7 +117,7 @@ public class MpOrderController {
         return orderFeignClient.getUpcomingDepartures(userId);
     }
 
-    @ApiOperation("各状态订单数量")
+    @ApiOperation(value = "各状态订单数量", notes = "统计当前用户各状态的订单数量，用于「我的」页面的订单状态角标展示\n\n**关联字典（BFF透传）**：\n- order_status：订单状态（状态分类统计）")
     @GetMapping("/count")
     public Result<Map<String, Object>> countByStatus(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java
index 6ddf62a..274102d 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java
@@ -21,7 +21,7 @@ public class MpPaymentController {
     private final MpPaymentFeignClient paymentFeignClient;
 
     @PostMapping("/prepay")
-    @ApiOperation(value = "发起支付", notes = "支付流程：选择支付方式(JSAPI/H5) → 调用微信支付API → 返回支付参数 → 前端调起微信支付")
+    @ApiOperation(value = "发起支付", notes = "支付流程：选择支付方式(JSAPI/H5) → 调用微信支付API → 返回支付参数 → 前端调起微信支付\n\n**关联字典（BFF透传）**：\n- payment_status：支付状态（返回字段）")
     public Result<Map<String, Object>> prepay(
             HttpServletRequest httpRequest,
             @ApiParam("支付请求体") @RequestBody MpPaymentPrepayRequest request) {
@@ -30,7 +30,7 @@ public class MpPaymentController {
     }
 
     @GetMapping("/status/{orderId}")
-    @ApiOperation("查询支付状态")
+    @ApiOperation(value = "查询支付状态", notes = "**关联字典（BFF透传）**：\n- payment_status：支付状态（显示）")
     public Result<Map<String, Object>> getStatus(@ApiParam("订单ID") @PathVariable Long orderId,
                                                   HttpServletRequest httpRequest) {
         Long userId = (Long) httpRequest.getAttribute("userId");
@@ -38,8 +38,8 @@ public class MpPaymentController {
     }
 
     @GetMapping("/transactions/{orderId}")
-    @ApiOperation("订单交易记录列表")
-    public Result<Object> listTransactions(@ApiParam("订单ID") @PathVariable Long orderId,
+    @ApiOperation(value = "订单交易记录列表", notes = "**关联字典（BFF透传）**：\n- payment_status：支付状态（显示）")
+    public Result<java.util.List<Map<String, Object>>> listTransactions(@ApiParam("订单ID") @PathVariable Long orderId,
                                             HttpServletRequest httpRequest) {
         Long userId = (Long) httpRequest.getAttribute("userId");
         return paymentFeignClient.listTransactions(userId, orderId);

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java
index 6aa9542..1aa236f 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java
@@ -34,7 +34,7 @@ public class MpProductController {
     private final MpOrderFeignClient orderFeignClient;
     private final ProductAggregationService productAggregationService;
 
-    @ApiOperation("产品列表")
+    @ApiOperation(value = "产品列表", notes = "分页查询已上架产品，支持按关键词、产品类型(CORE/ROUTE/CUSTOM/GROUP)、季节、天数、目的地、产品线筛选和排序\n\n**关联字典（BFF透传）**：\n- product_type：产品类型（列表筛选+显示）\n- product_status：产品状态（透传自product-service）")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listProducts(
             @ApiParam("搜索关键词") @RequestParam(required = false) String keyword,
@@ -63,7 +63,7 @@ public class MpProductController {
         return productFeignClient.listProducts(query);
     }
 
-    @ApiOperation(value = "产品详情（聚合收藏状态）", notes = "聚合流程：获取产品详情 → 并行查询收藏状态 → 异步记录足迹 → 返回聚合数据。支持未登录访问（不返回收藏状态）")
+    @ApiOperation(value = "产品详情（聚合收藏状态）", notes = "聚合流程：获取产品详情 → 并行查询收藏状态 → 异步记录足迹 → 返回聚合数据。支持未登录访问（不返回收藏状态）\n\n**关联字典（BFF透传）**：\n- product_type：产品类型（显示）\n- product_status：产品状态（透传自product-service）")
     @GetMapping("/{productId}")
     public Result<MpProductDetailVO> getProduct(HttpServletRequest request,
                                                  @ApiParam("产品ID") @PathVariable Long productId) {
@@ -256,7 +256,7 @@ public class MpProductController {
         }
     }
 
-    @ApiOperation("产品线列表")
+    @ApiOperation(value = "产品线列表", notes = "返回所有已启用的产品线，用于小程序首页或筛选栏展示")
     @GetMapping("/lines")
     public Result<List<Map<String, Object>>> listLines() {
         return productFeignClient.listActiveLines();
@@ -284,7 +284,7 @@ public class MpProductController {
         return productFeignClient.listBatchCombos(batchId);
     }
 
-    @ApiOperation("价格日历")
+    @ApiOperation(value = "价格日历", notes = "返回产品指定日期范围内的每日价格，用于日历组件展示。不传日期时默认返回未来一个月")
     @GetMapping("/{productId}/price-calendar")
     public Result<List<Map<String, Object>>> getPriceCalendar(
             @ApiParam("产品ID") @PathVariable Long productId,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java
index 5a72099..71890d6 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java
@@ -32,7 +32,7 @@ public class MpRefundController {
         return orderFeignClient.refundPreview(userId, orderId);
     }
 
-    @ApiOperation("退款原因列表")
+    @ApiOperation(value = "退款原因列表", notes = "返回系统预设的退款原因选项，用于退款申请页面的原因选择")
     @GetMapping("/refund-reasons")
     public Result<List<MpRefundReasonVO>> listRefundReasons() {
         return orderFeignClient.listRefundReasons();
@@ -48,7 +48,7 @@ public class MpRefundController {
         return orderFeignClient.applyRefund(userId, userName, orderId, body);
     }
 
-    @ApiOperation("退款申请详情")
+    @ApiOperation(value = "退款申请详情", notes = "获取退款申请的完整信息，包含审核状态、退款金额、退款进度和操作记录\n\n**关联字典（BFF透传）**：\n- order_status：订单状态（显示）\n- payment_status：支付/退款状态（显示）")
     @GetMapping("/refund/{applicationId}")
     public Result<MpRefundDetailVO> getRefundDetail(@ApiParam("退款申请ID") @PathVariable Long applicationId,
                                                        HttpServletRequest request) {
@@ -56,7 +56,7 @@ public class MpRefundController {
         return orderFeignClient.getRefundDetail(userId, applicationId);
     }
 
-    @ApiOperation("根据订单ID获取最新退款详情")
+    @ApiOperation(value = "根据订单ID获取最新退款详情", notes = "查询订单关联的最新一条退款申请详情，无退款记录时返回null\n\n**关联字典（BFF透传）**：\n- order_status：订单状态（显示）\n- payment_status：支付/退款状态（显示）")
     @GetMapping("/{orderId}/refund-detail")
     public Result<MpRefundDetailVO> getRefundDetailByOrder(@ApiParam("订单ID") @PathVariable String orderId,
                                                               HttpServletRequest request) {
@@ -84,7 +84,7 @@ public class MpRefundController {
         return orderFeignClient.refundAppeal(userId, applicationId, body);
     }
 
-    @ApiOperation("撤回退款申请")
+    @ApiOperation(value = "撤回退款申请", notes = "仅PENDING状态的退款申请可撤回，撤回后订单恢复到原状态")
     @PostMapping("/refund/{applicationId}/cancel")
     public Result<Void> cancelRefund(@ApiParam("退款申请ID") @PathVariable Long applicationId,
                                       HttpServletRequest request) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java
index 4b75e9b..38fa21b 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java
@@ -22,7 +22,8 @@ public class MpRestaurantController {
     private final MpResourceFeignClient resourceFeignClient;
     private final ResourceMapService resourceMapService;
 
-    @ApiOperation("餐厅列表")
+    @ApiOperation(value = "餐厅列表",
+            notes = "分页查询已上架的餐厅列表，支持按关键词和城市筛选。聚合层透传resource-service的餐厅数据。")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listRestaurants(
             @ApiParam("关键词") @RequestParam(required = false) String keyword,
@@ -37,7 +38,8 @@ public class MpRestaurantController {
         return resourceFeignClient.listRestaurants(query);
     }
 
-    @ApiOperation("餐厅详情")
+    @ApiOperation(value = "餐厅详情",
+            notes = "获取餐厅完整信息（含菜品、图文详情等），自动注入静态地图图片URL用于详情页地图展示。")
     @GetMapping("/{restaurantId}")
     public Result<Map<String, Object>> getRestaurantDetail(@ApiParam("餐厅ID") @PathVariable Long restaurantId) {
         Result<Map<String, Object>> result = resourceFeignClient.getRestaurantDetail(restaurantId);

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java
index 1f44df4..1cf55b2 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java
@@ -55,7 +55,7 @@ public class MpReviewController {
         return Result.success(categories);
     }
 
-    @ApiOperation(value = "创建评价", notes = "评价流程：订单完成后 → 查询可评价目标列表 → 对每个目标(酒店/景区/活动等)提交评价 → 自动内容审核 → 审核通过后公开展示")
+    @ApiOperation(value = "创建评价", notes = "评价流程：订单完成后 → 查询可评价目标列表 → 对每个目标(酒店/景区/活动等)提交评价 → 自动内容审核 → 审核通过后公开展示\n\n**关联字典（BFF透传）**：\n- review_status：评价审核状态（返回字段）\n- rating_level：评价等级（返回字段）")
     @PostMapping("/create")
     public Result<Map<String, Object>> createReview(@ApiParam("评价请求体") @RequestBody MpReviewCreateRequest body,
                                                      HttpServletRequest request) {
@@ -65,7 +65,7 @@ public class MpReviewController {
         return reviewFeignClient.createReview(body, userId);
     }
 
-    @ApiOperation("我的评价列表")
+    @ApiOperation(value = "我的评价列表", notes = "**关联字典（BFF透传）**：\n- review_status：评价审核状态（显示）\n- rating_level：评价等级（显示）")
     @GetMapping("/my")
     public Result<PageResult<Map<String, Object>>> getMyReviews(
             @ApiParam("页码") @RequestParam(defaultValue = "1") Integer page,
@@ -75,7 +75,7 @@ public class MpReviewController {
         return reviewFeignClient.getMyReviews(page, pageSize, userId);
     }
 
-    @ApiOperation(value = "关键词搜索评价(公开)", notes = "按关键词搜索已通过的评价内容，支持按目标类型和目标ID筛选")
+    @ApiOperation(value = "关键词搜索评价(公开)", notes = "按关键词搜索已通过的评价内容，支持按目标类型和目标ID筛选\n\n**关联字典（BFF透传）**：\n- rating_level：评价等级（显示）")
     @GetMapping("/search")
     public Result<PageResult<Map<String, Object>>> searchReviews(
             @ApiParam(value = "搜索关键词", required = true) @RequestParam String keyword,
@@ -86,7 +86,7 @@ public class MpReviewController {
         return reviewFeignClient.searchReviews(keyword, targetType, targetId, page, pageSize);
     }
 
-    @ApiOperation("某目标的已通过评价(公开)")
+    @ApiOperation(value = "某目标的已通过评价(公开)", notes = "**关联字典（BFF透传）**：\n- rating_level：评价等级（筛选+显示）")
     @GetMapping("/target")
     public Result<PageResult<Map<String, Object>>> getTargetReviews(
             @ApiParam("目标类型") @RequestParam String targetType,
@@ -102,7 +102,7 @@ public class MpReviewController {
         return reviewFeignClient.getTargetReviews(targetType, targetId, ratingLevel, hasImage, hasVideo, page, pageSize);
     }
 
-    @ApiOperation(value = "按产品ID查看评价列表", notes = "返回评价列表+统计数据，支持好中差评/有图/有视频筛选")
+    @ApiOperation(value = "按产品ID查看评价列表", notes = "返回评价列表+统计数据，支持好中差评/有图/有视频筛选\n\n**关联字典（BFF透传）**：\n- rating_level：评价等级（筛选+显示）")
     @GetMapping("/product/{productId}")
     public Result<Map<String, Object>> getProductReviews(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -144,7 +144,8 @@ public class MpReviewController {
         return reviewFeignClient.getProductHighlights(productId);
     }
 
-    @ApiOperation("评价统计(平均分、数量)")
+    @ApiOperation(value = "评价统计(平均分、数量)",
+            notes = "获取指定目标的评价统计数据（平均评分、总评价数等），用于详情页评价区域展示。产品showReview关闭时返回空统计。")
     @GetMapping("/stats")
     public Result<Map<String, Object>> getTargetStats(
             @ApiParam("目标类型") @RequestParam String targetType,
@@ -174,21 +175,23 @@ public class MpReviewController {
         return true; // 查询失败时默认显示
     }
 
-    @ApiOperation(value = "精选评价列表(公开)", notes = "无需登录，返回精选评价数组，用于评价浏览页")
+    @ApiOperation(value = "精选评价列表(公开)", notes = "无需登录，返回精选评价数组，用于评价浏览页\n\n**关联字典（BFF透传）**：\n- rating_level：评价等级（显示）")
     @GetMapping("/featured")
     public Result<List<Map<String, Object>>> getFeaturedReviews(
             @ApiParam("数量限制") @RequestParam(defaultValue = "50") Integer limit) {
         return reviewFeignClient.getFeaturedReviews(limit);
     }
 
-    @ApiOperation("检查订单是否已评价")
+    @ApiOperation(value = "检查订单是否已评价",
+            notes = "检查指定订单是否已提交评价，用于订单详情页决定是否显示'去评价'按钮。")
     @GetMapping("/order/{orderId}/reviewed")
     public Result<Boolean> isOrderReviewed(
             @ApiParam("订单ID") @PathVariable Long orderId) {
         return reviewFeignClient.isOrderReviewed(orderId);
     }
 
-    @ApiOperation("订单可评价目标列表")
+    @ApiOperation(value = "订单可评价目标列表",
+            notes = "返回订单中可评价的资源目标列表（景区/酒店/活动等），用于评价页面展示可评价项。已评价的目标不会重复出现。\n\n**权限**：需登录。")
     @GetMapping("/order/{orderId}/reviewable-targets")
     public Result<List<Map<String, Object>>> getReviewableTargets(
             @ApiParam("订单ID") @PathVariable Long orderId, HttpServletRequest request) {
@@ -196,7 +199,8 @@ public class MpReviewController {
         return reviewFeignClient.getReviewableTargets(orderId, userId);
     }
 
-    @ApiOperation("点赞/取消点赞评价")
+    @ApiOperation(value = "点赞/取消点赞评价",
+            notes = "对评价进行点赞或取消点赞操作，返回当前点赞状态和点赞总数。\n\n**权限**：需登录。")
     @PostMapping("/{reviewId}/like")
     public Result<Map<String, Object>> toggleLike(
             @ApiParam("评价ID") @PathVariable Long reviewId, HttpServletRequest request) {
@@ -204,7 +208,8 @@ public class MpReviewController {
         return reviewFeignClient.toggleLike(reviewId, userId);
     }
 
-    @ApiOperation("检查是否已点赞")
+    @ApiOperation(value = "检查是否已点赞",
+            notes = "检查当前用户是否已点赞指定评价，用于评价列表/详情的点赞按钮状态展示。\n\n**权限**：需登录。")
     @GetMapping("/{reviewId}/like/check")
     public Result<Boolean> checkLiked(
             @ApiParam("评价ID") @PathVariable Long reviewId, HttpServletRequest request) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java
index 96a4529..8f59647 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java
@@ -27,7 +27,8 @@ public class MpScenicController {
     private final MpUserFeignClient userFeignClient;
     private final ResourceMapService resourceMapService;
 
-    @ApiOperation("景区列表")
+    @ApiOperation(value = "景区列表",
+            notes = "分页查询已上架的景区列表，支持按关键词和城市筛选。聚合层透传resource-service的景区数据。")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listScenic(
             @ApiParam("关键词") @RequestParam(required = false) String keyword,
@@ -42,7 +43,8 @@ public class MpScenicController {
         return resourceFeignClient.listScenic(query);
     }
 
-    @ApiOperation("景区详情")
+    @ApiOperation(value = "景区详情",
+            notes = "获取景区完整信息（含季节素材、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。")
     @GetMapping("/{scenicId}")
     public Result<Map<String, Object>> getScenicDetail(@ApiParam("景区ID") @PathVariable Long scenicId) {
         Result<Map<String, Object>> result = resourceFeignClient.getScenicDetail(scenicId);
@@ -52,7 +54,8 @@ public class MpScenicController {
         return result;
     }
 
-    @ApiOperation("附近景区（地理+探索分类聚合）")
+    @ApiOperation(value = "附近景区（地理+探索分类聚合）",
+            notes = "聚合两个数据源：1.基于经纬度的地理位置附近景区（resource-service）；2.探索分类关联的景区（user-service）。去重合并后返回，用于景区详情页底部'附近推荐'展示。")
     @GetMapping("/{scenicId}/nearby")
     public Result<List<Map<String, Object>>> getNearbyScenic(
             @ApiParam("景区ID") @PathVariable Long scenicId,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java
index 7a2362a..689c544 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java
@@ -20,7 +20,7 @@ public class MpSearchController {
 
     private final MpProductFeignClient productFeignClient;
 
-    @ApiOperation("搜索产品")
+    @ApiOperation(value = "搜索产品", notes = "按关键词搜索已上架产品（匹配产品名称和描述），支持按产品类型进一步筛选\n\n**关联字典（BFF透传）**：\n- product_type：产品类型（筛选+显示）")
     @GetMapping
     public Result<PageResult<Map<String, Object>>> search(
             @ApiParam("搜索关键词") @RequestParam String keyword,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java
index 8831fd0..4f8f4d9 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java
@@ -22,7 +22,7 @@ public class MpTravelerController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("添加出行人")
+    @ApiOperation(value = "添加出行人", notes = "添加常用出行人信息（姓名/证件/联系方式等），下单时可快速选择。单个用户最多50个出行人")
     @PostMapping
     public Result<Map<String, Object>> addTraveler(HttpServletRequest request,
                                                     @RequestBody MpTravelerRequest body) {
@@ -31,21 +31,23 @@ public class MpTravelerController {
         return userFeignClient.addTraveler(userId, map);
     }
 
-    @ApiOperation("出行人列表")
+    @ApiOperation(value = "出行人列表", notes = "返回当前用户的所有出行人列表。如果用户已完善实名信息，列表中会自动包含一条「本人」虚拟记录(travelerId=0)")
     @GetMapping
     public Result<List<Map<String, Object>>> listTravelers(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.listTravelers(userId);
     }
 
-    @ApiOperation("出行人详情")
+    @ApiOperation(value = "出行人详情",
+            notes = "获取单个出行人的完整信息（姓名、证件信息、联系方式等）。\n\n**权限**：需登录，仅能查看自己的出行人。")
     @GetMapping("/{id}")
     public Result<Map<String, Object>> getTraveler(HttpServletRequest request, @ApiParam("出行人ID") @PathVariable Long id) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.getTraveler(userId, id);
     }
 
-    @ApiOperation("更新出行人")
+    @ApiOperation(value = "更新出行人",
+            notes = "修改出行人信息，支持部分更新（只传需要修改的字段）。已关联订单的出行人修改不影响历史订单记录。\n\n**权限**：需登录。")
     @PutMapping("/{id}")
     public Result<Map<String, Object>> updateTraveler(HttpServletRequest request,
                                                        @ApiParam("出行人ID") @PathVariable Long id,
@@ -55,14 +57,15 @@ public class MpTravelerController {
         return userFeignClient.updateTraveler(userId, id, map);
     }
 
-    @ApiOperation("删除出行人")
+    @ApiOperation(value = "删除出行人",
+            notes = "删除常用出行人记录。默认出行人不可删除，需先取消默认后再删除。\n\n**权限**：需登录。")
     @DeleteMapping("/{id}")
     public Result<Void> deleteTraveler(HttpServletRequest request, @ApiParam("出行人ID") @PathVariable Long id) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.deleteTraveler(userId, id);
     }
 
-    @ApiOperation("设为默认出行人")
+    @ApiOperation(value = "设为默认出行人", notes = "设为默认出行人后，下单时自动作为第一个出行人。每个用户只能有一个默认出行人")
     @PutMapping("/{id}/default")
     public Result<Void> setDefaultTraveler(HttpServletRequest request, @ApiParam("出行人ID") @PathVariable Long id) {
         Long userId = (Long) request.getAttribute("userId");

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java
index 5247c6f..9870345 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java
@@ -22,14 +22,14 @@ public class MpTripController {
     private final MpOrderFeignClient orderFeignClient;
     private final WeatherService weatherService;
 
-    @ApiOperation(value = "行程列表", notes = "获取当前登录用户的行程列表（已确认及进行中的订单对应的行程）")
+    @ApiOperation(value = "行程列表", notes = "获取当前登录用户的行程列表（已确认及进行中的订单对应的行程）\n\n**关联字典（BFF透传）**：\n- order_status：订单/行程状态（显示）")
     @GetMapping("/list")
     public Result<List<Map<String, Object>>> getTripList(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return orderFeignClient.getTripList(userId);
     }
 
-    @ApiOperation(value = "行程详情", notes = "获取订单对应的行程详情，含每日行程节点信息（景点/酒店/餐厅等）")
+    @ApiOperation(value = "行程详情", notes = "获取订单对应的行程详情，含每日行程节点信息（景点/酒店/餐厅等）\n\n**关联字典（BFF透传）**：\n- order_status：订单/行程状态（显示）")
     @GetMapping("/{orderId}")
     public Result<Map<String, Object>> getTripDetail(HttpServletRequest request,
                                                       @ApiParam(value = "订单ID", required = true) @PathVariable Long orderId) {
@@ -37,7 +37,7 @@ public class MpTripController {
         return orderFeignClient.getTripDetail(userId, orderId);
     }
 
-    @ApiOperation(value = "今日行程", notes = "获取今日行程（如果有正在进行中的行程），无行程时data为null")
+    @ApiOperation(value = "今日行程", notes = "获取今日行程（如果有正在进行中的行程），无行程时data为null\n\n**关联字典（BFF透传）**：\n- order_status：订单/行程状态（显示）")
     @GetMapping("/today")
     public Result<Map<String, Object>> getTodayTrip(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java
index 26146f8..249591a 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java
@@ -20,7 +20,7 @@ public class MpUserController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("发送短信验证码")
+    @ApiOperation(value = "发送短信验证码", notes = "向指定手机号发送登录验证码，有效期5分钟，60秒内不可重复发送")
     @PostMapping("/sms/send")
     public Result<Void> sendSmsCode(@RequestBody MpSmsSendRequest request) {
         Map<String, String> map = new java.util.HashMap<>();
@@ -45,14 +45,14 @@ public class MpUserController {
         return userFeignClient.login(map);
     }
 
-    @ApiOperation("获取用户信息")
+    @ApiOperation(value = "获取用户信息", notes = "获取当前登录用户的个人资料，包含头像、昵称、手机号、实名信息等")
     @GetMapping("/profile")
     public Result<Map<String, Object>> getProfile(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.getProfile(userId);
     }
 
-    @ApiOperation("更新用户信息")
+    @ApiOperation(value = "更新用户信息", notes = "更新当前用户的个人资料，支持部分更新（只传需要修改的字段）。首次完善资料时realName为必填")
     @PutMapping("/profile")
     public Result<Map<String, Object>> updateProfile(HttpServletRequest request,
                                                       @RequestBody MpUserProfileUpdateRequest body) {
@@ -69,7 +69,8 @@ public class MpUserController {
         return userFeignClient.updateProfile(userId, map);
     }
 
-    @ApiOperation("用户登出")
+    @ApiOperation(value = "用户登出",
+            notes = "清除用户登录状态和服务端缓存的令牌信息。登出后需重新登录获取新令牌。\n\n**权限**：需登录。")
     @PostMapping("/logout")
     public Result<Void> logout(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java
index 9341450..592fba5 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java
@@ -19,21 +19,21 @@ public class MpWeatherController {
 
     private final MpOrderFeignClient orderFeignClient;
 
-    @ApiOperation("获取订单行程天气")
+    @ApiOperation(value = "获取订单行程天气", notes = "根据订单行程中的目的地城市，批量查询每日天气信息，用于行程详情页展示")
     @GetMapping("/itinerary/{orderId}")
     public Result<List<Map<String, Object>>> getItineraryWeather(
             @ApiParam("订单ID") @PathVariable Long orderId) {
         return orderFeignClient.getItineraryWeather(orderId);
     }
 
-    @ApiOperation("获取指定城市实况天气")
+    @ApiOperation(value = "获取指定城市实况天气", notes = "通过高德天气API查询指定城市的实时天气（温度、湿度、风向等）")
     @GetMapping("/live")
     public Result<Map<String, Object>> getLiveWeather(
             @ApiParam("城市名称") @RequestParam String city) {
         return orderFeignClient.getLiveWeather(city);
     }
 
-    @ApiOperation("获取指定城市天气预报")
+    @ApiOperation(value = "获取指定城市天气预报", notes = "通过高德天气API查询指定城市未来3天的天气预报信息")
     @GetMapping("/forecast")
     public Result<Map<String, Object>> getForecastWeather(
             @ApiParam("城市名称") @RequestParam String city) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java
index 26fe4ac..c70bd36 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java
@@ -20,13 +20,15 @@ public class MpWikiController {
 
     private final MpWikiFeignClient wikiFeignClient;
 
-    @ApiOperation("攻略分类列表")
+    @ApiOperation(value = "攻略分类列表",
+            notes = "获取所有已启用的攻略分类，按排序值排列。用于小程序攻略频道的分类导航展示。")
     @GetMapping("/categories")
     public Result<List<Map<String, Object>>> listCategories() {
         return wikiFeignClient.listEnabledCategories();
     }
 
-    @ApiOperation("分类文章列表")
+    @ApiOperation(value = "分类文章列表",
+            notes = "分页查询指定攻略分类下已发布的文章列表，按发布时间倒序排列。用于攻略分类详情页。")
     @GetMapping("/category/{categoryId}/articles")
     public Result<PageResult<Map<String, Object>>> listCategoryArticles(
             @ApiParam("攻略分类ID") @PathVariable Long categoryId,
@@ -35,13 +37,14 @@ public class MpWikiController {
         return wikiFeignClient.listCategoryArticles(categoryId, page, pageSize);
     }
 
-    @ApiOperation("文章详情")
+    @ApiOperation(value = "文章详情", notes = "**关联字典（BFF透传）**：\n- wiki_status：文章状态（返回字段）")
     @GetMapping("/article/{articleId}")
     public Result<Map<String, Object>> getArticle(@ApiParam("文章ID") @PathVariable Long articleId) {
         return wikiFeignClient.getArticle(articleId);
     }
 
-    @ApiOperation("推荐文章列表")
+    @ApiOperation(value = "推荐文章列表",
+            notes = "获取编辑推荐的攻略文章列表（按推荐权重排序），用于首页或攻略频道的推荐位展示。")
     @GetMapping("/recommend-articles")
     public Result<List<Map<String, Object>>> listRecommendArticles(
             @ApiParam("返回条数") @RequestParam(defaultValue = "10") Integer limit) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java` (M)

接口变更 diff：

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java
index f9abab8..d9d2416 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java
@@ -21,14 +21,14 @@ public class MpWishController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("心愿单列表")
+    @ApiOperation(value = "心愿单列表", notes = "返回当前用户的心愿单列表，按创建时间倒序排列")
     @GetMapping
     public Result<List<Map<String, Object>>> listWishes(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.listWishes(userId);
     }
 
-    @ApiOperation("创建心愿")
+    @ApiOperation(value = "创建心愿", notes = "创建旅行心愿，描述想去的地方和时间偏好，定制师可据此推荐产品")
     @PostMapping
     public Result<Map<String, Object>> createWish(@ApiParam("心愿请求体") @RequestBody MpWishCreateRequest body,
                                                    HttpServletRequest request) {

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java
index 9b8e419..dce7686 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java
@@ -28,7 +28,7 @@ public class AdminAlbumController {
 
     // ==================== 文件夹管理 ====================
 
-    @ApiOperation("创建相册文件夹")
+    @ApiOperation(value = "创建相册文件夹", notes = "为订单创建旅行相册文件夹（如'第一天风景'、'合影'等），用于组织旅途照片/视频")
     @PostMapping("/{orderId}/album/folder")
     public Result<AlbumFolderVO> createFolder(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -38,7 +38,7 @@ public class AdminAlbumController {
         return Result.success(albumService.createFolder(orderId, request, adminId));
     }
 
-    @ApiOperation("编辑相册文件夹")
+    @ApiOperation(value = "编辑相册文件夹", notes = "修改文件夹名称或描述。仅创建者或超级管理员可操作")
     @PutMapping("/album/folder/{folderId}")
     public Result<AlbumFolderVO> updateFolder(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -49,7 +49,7 @@ public class AdminAlbumController {
         return Result.success(albumService.updateFolder(folderId, request, adminId, roleKey));
     }
 
-    @ApiOperation("删除相册文件夹")
+    @ApiOperation(value = "删除相册文件夹", notes = "删除文件夹及其下所有文件。仅创建者或超级管理员可操作。删除后C端用户不再可见")
     @DeleteMapping("/album/folder/{folderId}")
     public Result<Void> deleteFolder(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -60,7 +60,8 @@ public class AdminAlbumController {
         return Result.success(null);
     }
 
-    @ApiOperation("查询订单的文件夹列表")
+    @ApiOperation(value = "查询订单的文件夹列表",
+            notes = "获取指定订单的所有相册文件夹，含文件夹名称、描述、封面图、文件数量等信息。")
     @GetMapping("/{orderId}/album/folders")
     public Result<List<AlbumFolderVO>> listFolders(
             @ApiParam("订单ID") @PathVariable Long orderId) {
@@ -69,7 +70,11 @@ public class AdminAlbumController {
 
     // ==================== 文件管理 ====================
 
-    @ApiOperation("批量添加文件到文件夹")
+    @ApiOperation(value = "批量添加文件到文件夹", notes = "一次添加多个照片/视频到指定文件夹。文件需先通过文件服务上传获取OSS URL\n\n" +
+            "**关联字典**：\n" +
+            "- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频\n" +
+            "- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PostMapping("/album/folder/{folderId}/files")
     public Result<List<AlbumFileVO>> addFiles(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -80,7 +85,10 @@ public class AdminAlbumController {
         return Result.success(albumService.addFiles(folderId, request, adminId, roleKey));
     }
 
-    @ApiOperation("编辑文件信息")
+    @ApiOperation(value = "编辑文件信息", notes = "**关联字典**：\n" +
+            "- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频\n" +
+            "- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PutMapping("/album/file/{albumFileId}")
     public Result<AlbumFileVO> updateFile(
             @ApiParam("相册文件ID") @PathVariable Long albumFileId,
@@ -91,7 +99,8 @@ public class AdminAlbumController {
         return Result.success(albumService.updateFile(albumFileId, request, adminId, roleKey));
     }
 
-    @ApiOperation("删除文件")
+    @ApiOperation(value = "删除文件",
+            notes = "删除相册中的单个文件（照片/视频）。仅上传者或超级管理员可操作，删除后C端用户不再可见。")
     @DeleteMapping("/album/file/{albumFileId}")
     public Result<Void> deleteFile(
             @ApiParam("相册文件ID") @PathVariable Long albumFileId,
@@ -102,7 +111,10 @@ public class AdminAlbumController {
         return Result.success(null);
     }
 
-    @ApiOperation("查询文件夹下的文件列表")
+    @ApiOperation(value = "查询文件夹下的文件列表", notes = "**关联字典**：\n" +
+            "- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频\n" +
+            "- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @GetMapping("/album/folder/{folderId}/files")
     public Result<PageResult<AlbumFileVO>> listFiles(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -111,7 +123,8 @@ public class AdminAlbumController {
         return Result.success(albumService.listFiles(folderId, page, size));
     }
 
-    @ApiOperation("设置文件夹封面")
+    @ApiOperation(value = "设置文件夹封面",
+            notes = "将文件夹中的指定文件设为封面图，封面图会在文件夹列表中展示。仅上传者或超级管理员可操作。")
     @PutMapping("/album/folder/{folderId}/cover")
     public Result<Void> setCover(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -123,7 +136,11 @@ public class AdminAlbumController {
         return Result.success(null);
     }
 
-    @ApiOperation("我的上传（当前管理员上传的所有相册文件）")
+    @ApiOperation(value = "我的上传", notes = "查询当前管理员上传的所有相册文件（跨订单），方便管理自己上传的内容\n\n" +
+            "**关联字典**：\n" +
+            "- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频\n" +
+            "- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @GetMapping("/album/my-uploads")
     public Result<PageResult<AlbumFileVO>> listMyUploads(
             HttpServletRequest httpRequest,

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java
index 261c457..85b97c1 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java
@@ -31,7 +31,7 @@ public class AdminEarlyBirdController {
         }
     }
 
-    @ApiOperation("早鸟优惠计划列表")
+    @ApiOperation(value = "早鸟优惠计划列表", notes = "分页查询所有早鸟优惠计划。权限：仅超级管理员(SUPER_ADMIN)")
     @GetMapping("/list")
     public Result<PageResult<EarlyBirdPlanVO>> list(HttpServletRequest request,
                                                     @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -41,7 +41,7 @@ public class AdminEarlyBirdController {
         return Result.success(result);
     }
 
-    @ApiOperation("早鸟优惠计划详情")
+    @ApiOperation(value = "早鸟优惠计划详情", notes = "权限：仅超级管理员(SUPER_ADMIN)")
     @GetMapping("/{planId}")
     public Result<EarlyBirdPlanVO> detail(HttpServletRequest request,
                                           @ApiParam("早鸟计划ID") @PathVariable Long planId) {
@@ -50,7 +50,8 @@ public class AdminEarlyBirdController {
         return Result.success(vo);
     }
 
-    @ApiOperation("创建早鸟优惠计划")
+    @ApiOperation(value = "创建早鸟优惠计划", notes = "创建一个早鸟优惠计划，在指定日期范围内下单且满足最低人数条件的订单可享受优惠。\n" +
+            "下单时系统自动匹配最优的早鸟计划。权限：仅超级管理员(SUPER_ADMIN)")
     @PostMapping
     public Result<EarlyBirdPlanVO> create(HttpServletRequest request,
                                           @ApiParam("创建早鸟计划请求") @Valid @RequestBody EarlyBirdPlanRequest planRequest) {
@@ -61,7 +62,7 @@ public class AdminEarlyBirdController {
         return Result.success(vo);
     }
 
-    @ApiOperation("修改早鸟优惠计划")
+    @ApiOperation(value = "修改早鸟优惠计划", notes = "权限：仅超级管理员(SUPER_ADMIN)。修改不影响已下单的订单优惠")
     @PutMapping("/{planId}")
     public Result<Void> update(HttpServletRequest request,
                                @ApiParam("早鸟计划ID") @PathVariable Long planId,
@@ -71,7 +72,7 @@ public class AdminEarlyBirdController {
         return Result.success();
     }
 
-    @ApiOperation("删除早鸟优惠计划")
+    @ApiOperation(value = "删除早鸟优惠计划", notes = "权限：仅超级管理员(SUPER_ADMIN)。删除不影响已下单的订单优惠")
     @DeleteMapping("/{planId}")
     public Result<Void> delete(HttpServletRequest request,
                                @ApiParam("早鸟计划ID") @PathVariable Long planId) {
@@ -80,7 +81,7 @@ public class AdminEarlyBirdController {
         return Result.success();
     }
 
-    @ApiOperation("启用/禁用早鸟优惠计划")
+    @ApiOperation(value = "启用/禁用早鸟优惠计划", notes = "禁用后该计划不再参与自动匹配。权限：仅超级管理员(SUPER_ADMIN)")
     @PutMapping("/{planId}/toggle")
     public Result<Void> toggle(HttpServletRequest request,
                                @ApiParam("早鸟计划ID") @PathVariable Long planId,

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java
index de26a0f..d79934d 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java
@@ -27,7 +27,8 @@ public class AdminOrderConfigController {
     @Value("${order.expiry.redis-key:order:config:expiry-minutes}")
     private String expiryRedisKey;
 
-    @ApiOperation("获取订单过期配置")
+    @ApiOperation(value = "获取订单过期配置", notes = "获取当前的订单未支付自动过期时间（分钟）。\n" +
+            "返回当前值、默认值和配置来源（redis=已自定义, default=使用默认值）")
     @GetMapping("/expiry-minutes")
     public Result<Map<String, Object>> getExpiryMinutes() {
         String val = stringRedisTemplate.opsForValue().get(expiryRedisKey);
@@ -45,7 +46,8 @@ public class AdminOrderConfigController {
         ));
     }
 
-    @ApiOperation("设置订单过期时间（分钟）")
+    @ApiOperation(value = "设置订单过期时间（分钟）", notes = "修改订单未支付自动取消的等待时间。存储在Redis中，即时生效。\n" +
+            "仅影响新创建的订单，已有订单的过期时间不变")
     @PutMapping("/expiry-minutes")
     public Result<Void> setExpiryMinutes(@ApiParam("修改订单过期时间请求") @Valid @RequestBody UpdateExpiryMinutesRequest expiryRequest) {
         stringRedisTemplate.opsForValue().set(expiryRedisKey, String.valueOf(expiryRequest.getMinutes()));

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java
index e7f09ce..72bdfc8 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java
@@ -47,7 +47,18 @@ public class AdminOrderController {
     private static final String ORDER_CREATE_DEDUP = "order:admin:create:dedup:";
 
     @ApiOperation(value = "创建订单（定制师代下单）", notes = "创建订单流程：选择产品 → 填写联系人和出行人 → 系统计算报价 → 生成订单(PENDING_PAY状态)\n\n" +
-            "权限：CUSTOM产品仅创建者可下单，CORE/ROUTE产品所有管理员可下单")
+            "权限：CUSTOM产品仅创建者可下单，CORE/ROUTE产品所有管理员可下单\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 productType → 字典：product_type（产品类型）\n" +
+            "- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 请求参数 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）\n" +
+            "- 返回字段 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 返回字段 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 返回字段 travelers[].gender → 字典：gender（性别）")
     @PostMapping("/create")
     public Result<OrderDetailVO> createOrder(HttpServletRequest request,
                                              @ApiParam("创建订单请求") @Valid @RequestBody AdminCreateOrderRequest createRequest) {
@@ -69,21 +80,41 @@ public class AdminOrderController {
         }
     }
 
-    @ApiOperation("报价预览")
+    @ApiOperation(value = "报价预览", notes = "根据产品、出发日期、人数组合实时计算报价。\n" +
+            "返回各资源明细价格和合计金额，前端据此展示报价清单。\n\n" +
+            "注意：报价仅供参考，最终价格以创建订单时为准（价格日历可能变动）")
     @PostMapping("/quote")
     public Result<Map<String, Object>> quotePreview(@ApiParam("报价预览请求") @Valid @RequestBody QuotePreviewRequest quoteRequest) {
         Map<String, Object> result = orderService.quotePreview(quoteRequest);
         return Result.success(result);
     }
 
-    @ApiOperation("订单列表")
+    @ApiOperation(value = "订单列表", notes = "支持按关键词（订单号/联系人/产品名）、状态、内部流程状态、产品类型筛选。\n" +
+            "支持按创建时间/出发日期/总价排序。\n\n" +
+            "返回分页结果，包含订单基本信息、状态、支付信息和产品封面\n\n" +
+            "【关联字典】\n" +
+            "- 筛选参数 status → 字典：order_status（订单状态）\n" +
+            "- 筛选参数 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 筛选参数 productType → 字典：product_type（产品类型）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/list")
     public Result<PageResult<OrderListVO>> listOrders(@ApiParam("订单查询请求") AdminOrderQueryRequest request) {
         PageResult<OrderListVO> result = orderService.listAdminOrders(request);
         return Result.success(result);
     }
 
-    @ApiOperation("订单详情")
+    @ApiOperation(value = "订单详情", notes = "返回订单完整信息，包括：基本信息、产品快照、联系人、出行人列表、支付记录、优惠明细、时间线、内部流程状态等\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）\n" +
+            "- 返回字段 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 返回字段 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 返回字段 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 timeline[].action → 字典：order_timeline_action（订单操作类型）\n" +
+            "- 返回字段 todos[].todoType → 字典：order_todo_type（订单待办类型）")
     @GetMapping("/{orderId}")
     public Result<OrderDetailVO> getOrder(@ApiParam("订单ID") @PathVariable Long orderId) {
         OrderDetailVO detail = orderService.getAdminOrderDetail(orderId);
@@ -111,7 +142,9 @@ public class AdminOrderController {
             "- 旅行中 → 已完成\n" +
             "- 已完成 → 售后中\n" +
             "- 售后中 → 退款中\n" +
-            "- 退款中 → 已退款")
+            "- 退款中 → 已退款\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 status → 字典：order_status（订单状态）")
     @PutMapping("/{orderId}/status")
     public Result<Void> updateStatus(HttpServletRequest request,
                                         @ApiParam("订单ID") @PathVariable Long orderId,
@@ -134,7 +167,7 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("添加备注")
+    @ApiOperation(value = "添加备注", notes = "向订单时间线添加一条管理员备注。备注会记录操作人和时间，可用于内部沟通和订单跟踪")
     @PostMapping("/{orderId}/remark")
     public Result<Void> addRemark(HttpServletRequest request,
                                      @ApiParam("订单ID") @PathVariable Long orderId,
@@ -145,7 +178,8 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("修改定金金额")
+    @ApiOperation(value = "修改定金金额", notes = "修改订单的定金金额。仅待支付(PENDING_PAY)状态可修改。\n\n" +
+            "定金金额不能超过订单总价，修改后影响用户支付页面显示的应付金额")
     @PutMapping("/{orderId}/deposit")
     public Result<Void> updateDeposit(HttpServletRequest request,
                                       @ApiParam("订单ID") @PathVariable Long orderId,
@@ -156,7 +190,14 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("编辑订单")
+    @ApiOperation(value = "编辑订单", notes = "修改订单的联系人、人数、出发日期、售价、成本、备注等信息。\n" +
+            "仅传入需要修改的字段，未传入的字段不会被修改。\n\n" +
+            "如果提供了出行人列表(travelers)，将替换订单的全部出行人。\n" +
+            "已锁定的订单需先调用'申请修改'接口解锁后才能编辑\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 请求参数 travelers[].gender → 字典：gender（性别）")
     @PutMapping("/{orderId}")
     public Result<Void> editOrder(HttpServletRequest request,
                                   @ApiParam("订单ID") @PathVariable Long orderId,
@@ -167,7 +208,8 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("更新房间信息（仅房务管理员/超级管理员）")
+    @ApiOperation(value = "更新房间信息（仅房务管理员/超级管理员）",
+            notes = "更新订单的房间分配信息（房型、房间号、入住安排等）。\n\n**权限**：仅ROOM_MANAGER（房务管理员）或SUPER_ADMIN（超级管理员）可操作。")
     @PutMapping("/{orderId}/room-info")
     public Result<Void> updateRoomInfo(HttpServletRequest request,
                                        @ApiParam("订单ID") @PathVariable Long orderId,
@@ -183,7 +225,8 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("更新车辆信息（仅车务管理员/超级管理员）")
+    @ApiOperation(value = "更新车辆信息（仅车务管理员/超级管理员）",
+            notes = "更新订单的车辆分配信息（车型、车牌号、司机等）。\n\n**权限**：仅VEHICLE_MANAGER（车务管理员）或SUPER_ADMIN（超级管理员）可操作。")
     @PutMapping("/{orderId}/vehicle-info")
     public Result<Void> updateVehicleInfo(HttpServletRequest request,
                                           @ApiParam("订单ID") @PathVariable Long orderId,
@@ -210,7 +253,9 @@ public class AdminOrderController {
     }
 
     @ApiOperation(value = "推进内部流程", notes = "内部流程推进顺序：待配房(PENDING_ROOM) → 待配车(PENDING_VEHICLE) → 待核算(PENDING_FINANCE) → 就绪(READY)\n\n" +
-            "仅在订单状态为已确认(CONFIRMED)时有效，每次调用自动推进到下一步")
+            "仅在订单状态为已确认(CONFIRMED)时有效，每次调用自动推进到下一步\n\n" +
+            "【关联字典】\n" +
+            "- 涉及字段 processStatus → 字典：order_process_status（订单内部流程状态）")
     @PutMapping("/{orderId}/process-status")
     public Result<Void> advanceProcessStatus(HttpServletRequest request,
                                              @ApiParam("订单ID") @PathVariable Long orderId) {
@@ -220,7 +265,8 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("添加优惠项")
+    @ApiOperation(value = "添加优惠项", notes = "为订单添加手动优惠（如会员折扣、老客优惠等）。\n" +
+            "添加后系统自动重算订单应付金额。一个订单可添加多个优惠项")
     @PostMapping("/{orderId}/discount")
     public Result<OrderDiscount> addDiscount(HttpServletRequest request,
                                              @ApiParam("订单ID") @PathVariable Long orderId,
@@ -231,7 +277,7 @@ public class AdminOrderController {
         return Result.success(discount);
     }
 
-    @ApiOperation("修改优惠项")
+    @ApiOperation(value = "修改优惠项", notes = "修改已添加的优惠项名称或金额，修改后自动重算订单应付金额")
     @PutMapping("/{orderId}/discount/{discountId}")
     public Result<Void> updateDiscount(HttpServletRequest request,
                                        @ApiParam("订单ID") @PathVariable Long orderId,
@@ -243,7 +289,7 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("删除优惠项")
+    @ApiOperation(value = "删除优惠项", notes = "删除已添加的优惠项，删除后自动重算订单应付金额")
     @DeleteMapping("/{orderId}/discount/{discountId}")
     public Result<Void> removeDiscount(HttpServletRequest request,
                                        @ApiParam("订单ID") @PathVariable Long orderId,
@@ -296,7 +342,8 @@ public class AdminOrderController {
         return Result.success(diff);
     }
 
-    @ApiOperation("分配车辆信息")
+    @ApiOperation(value = "分配车辆信息", notes = "为订单分配具体的车辆和司机信息（车型、品牌、车牌号、司机姓名和电话）。\n" +
+            "分配后信息将展示在订单详情和C端行程中")
     @PutMapping("/{orderId}/vehicle-assignment")
     public Result<Void> assignVehicle(@ApiParam("订单ID") @PathVariable Long orderId,
                                       @RequestBody @Valid VehicleAssignmentRequest request) {
@@ -304,7 +351,8 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("分配酒店信息")
+    @ApiOperation(value = "分配酒店信息", notes = "按家庭为订单分配具体的酒店房间（酒店名称、房型、入住/退房日期）。\n" +
+            "每个家庭对应一条分配记录，分配后信息将展示在订单详情和C端行程中")
     @PutMapping("/{orderId}/hotel-assignment")
     public Result<Void> assignHotel(@ApiParam("订单ID") @PathVariable Long orderId,
                                      @RequestBody @Valid HotelAssignmentRequest request) {
@@ -312,7 +360,7 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("设置尾款支付方式")
+    @ApiOperation(value = "设置尾款支付方式", notes = "设置订单尾款的支付方式。ONLINE=线上微信支付，OFFLINE=线下转账（需管理员手动记录尾款到账）")

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java
index 83ae39c..9ab5d5e 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java
@@ -31,7 +31,11 @@ public class AdminOrderItineraryController {
     private final OrderItineraryEditService itineraryEditService;
     private final OrderPriceDiffService priceDiffService;
 
-    @ApiOperation(value = "跳过节点", notes = "将行程中的某个节点标记为跳过（客户不去）")
+    @ApiOperation(value = "跳过节点", notes = "将行程中的某个节点标记为跳过（客户不去）\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PostMapping("/skip")
     public Result<OrderItineraryEdit> skipNode(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -43,7 +47,10 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.skipNode(orderId, request, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "恢复跳过的节点", notes = "取消跳过，恢复为正常状态")
+    @ApiOperation(value = "恢复跳过的节点", notes = "取消跳过，恢复为正常状态\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @DeleteMapping("/skip/{editId}")
     public Result<Void> unskipNode(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -58,7 +65,11 @@ public class AdminOrderItineraryController {
         return Result.success();
     }
 
-    @ApiOperation(value = "新增节点", notes = "在某一天的行程中新增一个节点")
+    @ApiOperation(value = "新增节点", notes = "在某一天的行程中新增一个节点\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PostMapping("/add")
     public Result<OrderItineraryEdit> addNode(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -76,7 +87,10 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.addNode(orderId, request, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "删除新增的节点", notes = "删除通过编辑新增的节点")
+    @ApiOperation(value = "删除新增的节点", notes = "删除通过编辑新增的节点\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @DeleteMapping("/add/{editId}")
     public Result<Void> removeAddedNode(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -91,7 +105,10 @@ public class AdminOrderItineraryController {
         return Result.success();
     }
 
-    @ApiOperation("获取合并后的行程（原始+编辑）")
+    @ApiOperation(value = "获取合并后的行程（原始+编辑）", notes = "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @GetMapping("/merged")
     public Result<List<Map<String, Object>>> getMergedItinerary(
             @ApiParam("订单ID") @PathVariable Long orderId) {
@@ -105,14 +122,19 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.getBalanceAdjustmentSummary(orderId));
     }
 
-    @ApiOperation("获取行程编辑记录列表")
+    @ApiOperation(value = "获取行程编辑记录列表", notes = "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @GetMapping("/edits")
     public Result<List<OrderItineraryEdit>> getEditList(
             @ApiParam("订单ID") @PathVariable Long orderId) {
         return Result.success(itineraryEditService.getEditList(orderId));
     }
 
-    @ApiOperation(value = "房型切换差价预览", notes = "预览房型切换的差价，不创建记录")
+    @ApiOperation(value = "房型切换差价预览", notes = "预览房型切换的差价，不创建记录\n\n" +
+            "**关联字典**：\n" +
+            "- resource_type（资源类型，返回字段resourceType）：HOTEL=酒店")
     @PostMapping("/room-type-change/preview")
     public Result<PriceDiffVO> previewRoomTypeChange(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -120,7 +142,11 @@ public class AdminOrderItineraryController {
         return Result.success(priceDiffService.previewRoomTypeDiff(orderId, request));
     }
 
-    @ApiOperation(value = "房型切换", notes = "执行房型切换，自动计算差价，创建待确认记录")
+    @ApiOperation(value = "房型切换", notes = "执行房型切换，自动计算差价，创建待确认记录\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：ROOM_CHANGE=房型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：HOTEL=酒店")
     @PostMapping("/room-type-change")
     public Result<OrderItineraryEdit> roomTypeChange(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -132,7 +158,9 @@ public class AdminOrderItineraryController {
         return Result.success(priceDiffService.executeRoomTypeChange(orderId, request, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "车型切换差价预览", notes = "预览车型切换的差价，不创建记录")
+    @ApiOperation(value = "车型切换差价预览", notes = "预览车型切换的差价，不创建记录\n\n" +
+            "**关联字典**：\n" +
+            "- resource_type（资源类型，返回字段resourceType）：VEHICLE=车辆")
     @PostMapping("/vehicle-type-change/preview")
     public Result<PriceDiffVO> previewVehicleTypeChange(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -140,7 +168,11 @@ public class AdminOrderItineraryController {
         return Result.success(priceDiffService.previewVehicleTypeDiff(orderId, request));
     }
 
-    @ApiOperation(value = "车型切换", notes = "执行车型切换，自动计算差价，创建待确认记录")
+    @ApiOperation(value = "车型切换", notes = "执行车型切换，自动计算差价，创建待确认记录\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：VEHICLE=车辆")
     @PostMapping("/vehicle-type-change")
     public Result<OrderItineraryEdit> vehicleTypeChange(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -152,7 +184,11 @@ public class AdminOrderItineraryController {
         return Result.success(priceDiffService.executeVehicleTypeChange(orderId, request, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "新增整天行程", notes = "在订单行程中新增一整天（含多个节点）")
+    @ApiOperation(value = "新增整天行程", notes = "在订单行程中新增一整天（含多个节点）\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：ADD_DAY=新增整天\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PostMapping("/add-day")
     public Result<List<OrderItineraryEdit>> addDay(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -164,7 +200,9 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.addDay(orderId, request, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "删除新增的整天行程", notes = "删除通过新增操作添加的整天行程及其所有子节点，已确认的天不允许删除")
+    @ApiOperation(value = "删除新增的整天行程", notes = "删除通过新增操作添加的整天行程及其所有子节点，已确认的天不允许删除\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @DeleteMapping("/day/{editId}")
     public Result<Void> removeDay(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -179,7 +217,11 @@ public class AdminOrderItineraryController {
         return Result.success();
     }
 
-    @ApiOperation(value = "修改编辑记录", notes = "修改待确认状态的编辑记录（如调整价格、名称等）")
+    @ApiOperation(value = "修改编辑记录", notes = "修改待确认状态的编辑记录（如调整价格、名称等）\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PutMapping("/edit/{editId}")
     public Result<OrderItineraryEdit> updateEdit(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -192,7 +234,9 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.updateEdit(orderId, editId, updates, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "确认单条修改", notes = "确认一条待确认的行程编辑")
+    @ApiOperation(value = "确认单条修改", notes = "确认一条待确认的行程编辑\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @PostMapping("/confirm/{editId}")
     public Result<Void> confirmEdit(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -205,7 +249,9 @@ public class AdminOrderItineraryController {
         return Result.success();
     }
 
-    @ApiOperation(value = "批量确认所有待确认修改", notes = "确认该订单所有待确认的行程编辑")
+    @ApiOperation(value = "批量确认所有待确认修改", notes = "确认该订单所有待确认的行程编辑\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @PostMapping("/confirm-all")
     public Result<Integer> confirmAllPending(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -216,7 +262,9 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.confirmAllPending(orderId, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "撤回待确认的修改", notes = "软删除一条待确认的编辑记录")
+    @ApiOperation(value = "撤回待确认的修改", notes = "软删除一条待确认的编辑记录\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @DeleteMapping("/pending/{editId}")
     public Result<Void> withdrawPendingEdit(
             @ApiParam("订单ID") @PathVariable Long orderId,

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java
index d7339d2..f708a7f 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java
@@ -29,14 +29,21 @@ public class AdminOrderTodoController {
     private final OrderService orderService;
     private final UserFeignClient userFeignClient;
 
-    @ApiOperation("获取订单待办列表")
+    @ApiOperation(value = "获取订单待办列表", notes = "返回指定订单的所有待办项（含已完成和未完成）。\n" +
+            "待办类型包括：配房、配车、签合同、购保险、核算等，随内部流程自动生成\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 todoType → 字典：order_todo_type（订单待办类型）")
     @GetMapping("/{orderId}/todos")
     public Result<List<OrderTodo>> getOrderTodos(@ApiParam("订单ID") @PathVariable Long orderId) {
         List<OrderTodo> todos = orderTodoService.listByOrderId(orderId);
         return Result.success(todos);
     }
 
-    @ApiOperation("完成待办")
+    @ApiOperation(value = "完成待办", notes = "将指定待办标记为已完成。\n" +
+            "需要对应角色权限：如配房待办需ROOM_MANAGER角色，配车待办需VEHICLE_MANAGER角色。\n\n" +
+            "完成后系统自动检查是否所有必要待办已完成，若是则推进内部流程\n\n" +
+            "【关联字典】\n" +
+            "- 涉及字段 todoType → 字典：order_todo_type（订单待办类型）")
     @PutMapping("/todo/{todoId}/complete")
     public Result<Void> completeTodo(HttpServletRequest request,
                                      @ApiParam("待办ID") @PathVariable Long todoId) {
@@ -47,7 +54,11 @@ public class AdminOrderTodoController {
         return Result.success();
     }
 
-    @ApiOperation("我的待办列表")
+    @ApiOperation(value = "我的待办列表", notes = "根据当前管理员ID和角色，查询分配给自己的未完成待办。\n" +
+            "超级管理员可看到所有待办，其他角色只能看到对应类型的待办\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 todoType → 字典：order_todo_type（订单待办类型）\n" +
+            "- 返回字段 orderStatus → 字典：order_status（订单状态）")
     @GetMapping("/todo/my-list")
     public Result<List<OrderTodoVO>> getMyTodos(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -56,7 +67,7 @@ public class AdminOrderTodoController {
         return Result.success(todos);
     }
 
-    @ApiOperation("我的待办数量")
+    @ApiOperation(value = "我的待办数量", notes = "返回当前管理员未完成的待办总数，用于首页角标/红点提醒")
     @GetMapping("/todo/my-count")
     public Result<Integer> getMyTodosCount(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -65,7 +76,7 @@ public class AdminOrderTodoController {
         return Result.success(count);
     }
 
-    @ApiOperation("定制师列表")
+    @ApiOperation(value = "定制师列表", notes = "获取所有定制师(CUSTOMIZER角色)的列表，用于更换定制师时选择目标定制师")
     @GetMapping("/todo/customizer-list")
     public Result<List<AdminBasicDTO>> getCustomizerList() {
         try {
@@ -79,7 +90,7 @@ public class AdminOrderTodoController {
         return Result.success(Collections.emptyList());
     }
 
-    @ApiOperation("更换定制师")
+    @ApiOperation(value = "更换定制师", notes = "将订单转派给另一位定制师。更换后原定制师的待办自动转移，订单时间线会记录此操作")
     @PutMapping("/{orderId}/customizer")
     public Result<Void> changeCustomizer(HttpServletRequest request,
                                          @ApiParam("订单ID") @PathVariable Long orderId,
@@ -90,7 +101,11 @@ public class AdminOrderTodoController {
         return Result.success();
     }
 
-    @ApiOperation("可签合同订单列表（保险已完成）")
+    @ApiOperation(value = "可签合同订单列表（保险已完成）", notes = "查询保险待办已完成、可以进入签合同环节的订单列表。\n" +
+            "用于合同管理页面展示待签合同的订单\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 todoType → 字典：order_todo_type（订单待办类型）\n" +
+            "- 返回字段 orderStatus → 字典：order_status（订单状态）")
     @GetMapping("/todo/contract-eligible")
     public Result<List<OrderTodoVO>> getContractEligibleOrders(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java
index fddef53..eb92d44 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java
@@ -31,7 +31,11 @@ public class AdminRefundController {
 
     // ==================== Refund Applications ====================
 
-    @ApiOperation("退款申请列表")
+    @ApiOperation(value = "退款申请列表", notes = "分页查询退款申请，支持按状态筛选。\n" +
+            "状态包括：PENDING(待审批)、APPROVED(已通过)、REJECTED(已拒绝)、REFUNDING(退款中)、REFUNDED(已退款)、CANCELLED(已撤回)、APPEAL(申诉中)\n\n" +
+            "【关联字典】\n" +
+            "- 筛选参数 status → 字典：refund_status（退款状态）\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @GetMapping("/list")
     public Result<PageResult<RefundApplicationVO>> listApplications(
             @ApiParam("状态") @RequestParam(required = false) String status,
@@ -40,14 +44,18 @@ public class AdminRefundController {
         return Result.success(refundApplicationService.listApplications(status, page, pageSize));
     }
 
-    @ApiOperation("退款申请详情")
+    @ApiOperation(value = "退款申请详情", notes = "返回退款申请的完整信息，包括退款原因、申请金额、实退金额、审批记录、申诉信息等\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @GetMapping("/{applicationId}")
     public Result<RefundApplicationVO> getDetail(@ApiParam("退款申请ID") @PathVariable Long applicationId) {
         return Result.success(refundApplicationService.getDetail(applicationId));
     }
 
     @ApiOperation(value = "审批退款申请", notes = "退款审批流程：查看退款申请 → 决定通过/拒绝 → 通过时填写实退金额 → 系统自动调起微信退款\n\n" +
-            "拒绝后用户可发起申诉")
+            "拒绝后用户可发起申诉\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @PutMapping("/{applicationId}/review")
     public Result<RefundApplicationVO> review(HttpServletRequest request,
                                                @ApiParam("退款申请ID") @PathVariable Long applicationId,
@@ -79,20 +87,26 @@ public class AdminRefundController {
 
     // ==================== Refund Reasons ====================
 
-    @ApiOperation("退款原因列表")
+    @ApiOperation(value = "退款原因列表", notes = "获取所有退款原因选项（含禁用的），用于退款原因管理页面\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 category → 字典：refund_reason_category（退款原因分类）")
     @GetMapping("/reason/list")
     public Result<List<RefundReasonVO>> listReasons() {
         return Result.success(refundReasonService.listReasons(false));
     }
 
-    @ApiOperation("创建退款原因")
+    @ApiOperation(value = "创建退款原因", notes = "新增退款原因选项，C端用户申请退款时可选择。按sortOrder排序展示\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 category → 字典：refund_reason_category（退款原因分类）")
     @PostMapping("/reason")
     public Result<RefundReasonVO> createReason(@ApiParam("创建退款原因请求") @Valid @RequestBody CreateRefundReasonRequest createRequest) {
         return Result.success(refundReasonService.createReason(
                 createRequest.getReasonText(), createRequest.getCategory(), createRequest.getSortOrder()));
     }
 
-    @ApiOperation("修改退款原因")
+    @ApiOperation(value = "修改退款原因", notes = "修改退款原因的文本、分类或排序，不影响已使用该原因的历史退款申请\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 category → 字典：refund_reason_category（退款原因分类）")
     @PutMapping("/reason/{reasonId}")
     public Result<RefundReasonVO> updateReason(@ApiParam("退款原因ID") @PathVariable Long reasonId,
                                                 @ApiParam("修改退款原因请求") @Valid @RequestBody UpdateRefundReasonRequest updateRequest) {
@@ -100,7 +114,7 @@ public class AdminRefundController {
                 reasonId, updateRequest.getReasonText(), updateRequest.getCategory(), updateRequest.getSortOrder()));
     }
 
-    @ApiOperation("删除退款原因")
+    @ApiOperation(value = "删除退款原因", notes = "软删除退款原因，删除后C端不再展示。不影响已使用该原因的历史退款申请")
     @DeleteMapping("/reason/{reasonId}")
     public Result<Void> deleteReason(@ApiParam("退款原因ID") @PathVariable Long reasonId) {
         refundReasonService.deleteReason(reasonId);

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java
index 9ff5005..e1bc0c8 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java
@@ -22,13 +22,17 @@ public class AdminRefundPolicyController {
 
     private final RefundPolicyService refundPolicyService;
 
-    @ApiOperation("退款政策列表")
+    @ApiOperation(value = "退款政策列表", notes = "【关联字典】\n" +
+            "- 返回字段 refundType → 字典：refund_type（退款类型）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/list")
     public Result<List<RefundPolicyVO>> list() {
         return Result.success(refundPolicyService.listPolicies());
     }
 
-    @ApiOperation("退款政策详情")
+    @ApiOperation(value = "退款政策详情", notes = "【关联字典】\n" +
+            "- 返回字段 refundType → 字典：refund_type（退款类型）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/{policyId}")
     public Result<RefundPolicyVO> detail(@ApiParam("退款政策ID") @PathVariable Long policyId) {
         return Result.success(refundPolicyService.getDetail(policyId));
@@ -36,7 +40,10 @@ public class AdminRefundPolicyController {
 
     @ApiOperation(value = "创建退款政策", notes = "退款政策定义按产品类型和距出发天数的退款比例阶梯\n\n" +
             "例如：出发前30天退90%，前15天退70%，前7天退50%，7天内不可退\n\n" +
-            "每种产品类型可配置独立的退款政策，用户申请退款时系统自动匹配")
+            "每种产品类型可配置独立的退款政策，用户申请退款时系统自动匹配\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 refundType → 字典：refund_type（退款类型）\n" +
+            "- 请求参数 productType → 字典：product_type（产品类型）")
     @PostMapping
     public Result<RefundPolicyVO> create(HttpServletRequest request,
                                           @ApiParam("创建退款政策请求") @Valid @RequestBody RefundPolicyRequest policyRequest) {
@@ -44,14 +51,17 @@ public class AdminRefundPolicyController {
         return Result.success(refundPolicyService.createPolicy(policyRequest, adminId));
     }
 
-    @ApiOperation("修改退款政策")
+    @ApiOperation(value = "修改退款政策", notes = "【关联字典】\n" +
+            "- 请求参数 refundType → 字典：refund_type（退款类型）\n" +
+            "- 请求参数 productType → 字典：product_type（产品类型）")
     @PutMapping("/{policyId}")
     public Result<RefundPolicyVO> update(@ApiParam("退款政策ID") @PathVariable Long policyId,
                                           @ApiParam("修改退款政策请求") @Valid @RequestBody RefundPolicyRequest policyRequest) {
         return Result.success(refundPolicyService.updatePolicy(policyId, policyRequest));
     }
 
-    @ApiOperation("删除退款政策")
+    @ApiOperation(value = "删除退款政策",
+            notes = "软删除退款政策。删除后该产品类型将使用默认退款规则。不影响已使用该政策处理的历史退款申请。")
     @DeleteMapping("/{policyId}")
     public Result<Void> delete(@ApiParam("退款政策ID") @PathVariable Long policyId) {
         refundPolicyService.deletePolicy(policyId);

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java
index 949f142..faf973b 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java
@@ -25,7 +25,15 @@ public class AdminWorkOrderController {
 
     private final WorkOrderService workOrderService;
 
-    @ApiOperation("工单列表")
+    @ApiOperation(value = "工单列表", notes = "分页查询工单，支持按状态/类型/优先级/订单编号/处理人筛选。\n" +
+            "工单用于处理旅行中的突发变更需求（如换房、换车、加景点等）\n\n" +
+            "【关联字典】\n" +
+            "- 筛选参数 status → 字典：work_order_status（工单状态）\n" +
+            "- 筛选参数 type → 字典：work_order_type（工单类型）\n" +
+            "- 筛选参数 priority → 字典：work_order_priority（工单优先级）\n" +
+            "- 返回字段 status → 字典：work_order_status（工单状态）\n" +
+            "- 返回字段 type → 字典：work_order_type（工单类型）\n" +
+            "- 返回字段 priority → 字典：work_order_priority（工单优先级）")
     @GetMapping("/list")
     public Result<PageResult<WorkOrderVO>> list(
             @ApiParam("状态: PENDING/PROCESSING/RESOLVED/REJECTED") @RequestParam(required = false) String status,
@@ -38,19 +46,32 @@ public class AdminWorkOrderController {
         return Result.success(workOrderService.listWorkOrders(status, type, priority, orderNo, assigneeAdminId, page, pageSize));
     }
 
-    @ApiOperation("工单详情")
+    @ApiOperation(value = "工单详情", notes = "返回工单完整信息，包括关联订单、资源详情、处理记录和备注列表\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：work_order_status（工单状态）\n" +
+            "- 返回字段 type → 字典：work_order_type（工单类型）\n" +
+            "- 返回字段 priority → 字典：work_order_priority（工单优先级）")
     @GetMapping("/{workOrderId}")
     public Result<WorkOrderVO> getDetail(@ApiParam("工单ID") @PathVariable Long workOrderId) {
         return Result.success(workOrderService.getDetail(workOrderId));
     }
 
-    @ApiOperation("工单统计(待处理数等)")
+    @ApiOperation(value = "工单统计", notes = "返回各状态的工单数量和紧急工单数，用于工单管理页面顶部统计卡片\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段中的状态key → 字典：work_order_status（工单状态）")
     @GetMapping("/stats")
     public Result<Map<String, Object>> getStats() {
         return Result.success(workOrderService.getStats());
     }
 
-    @ApiOperation("创建工单")
+    @ApiOperation(value = "创建工单", notes = "创建旅途中的变更工单，需关联订单ID。\n" +
+            "可指定处理人，未指定则进入待分配状态。可附带差价信息和资源详情JSON\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 type → 字典：work_order_type（工单类型）\n" +
+            "- 请求参数 priority → 字典：work_order_priority（工单优先级）\n" +
+            "- 返回字段 status → 字典：work_order_status（工单状态）\n" +
+            "- 返回字段 type → 字典：work_order_type（工单类型）\n" +
+            "- 返回字段 priority → 字典：work_order_priority（工单优先级）")
     @PostMapping
     public Result<WorkOrderVO> create(HttpServletRequest request,
                                        @Valid @RequestBody CreateWorkOrderRequest body) {
@@ -59,7 +80,10 @@ public class AdminWorkOrderController {
         return Result.success(workOrderService.createWorkOrder(adminId, adminName, body));
     }
 
-    @ApiOperation("处理工单(解决/驳回)")
+    @ApiOperation(value = "处理工单（解决/驳回）", notes = "解决时需填写处理结果(resolution)，驳回时需填写驳回原因(rejectReason)。\n" +
+            "可调整差价(costDifference)，正数表示加价，负数表示退费\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：work_order_status（工单状态）")
     @PutMapping("/{workOrderId}/process")
     public Result<WorkOrderVO> process(HttpServletRequest request,
                                         @ApiParam("工单ID") @PathVariable Long workOrderId,
@@ -69,7 +93,7 @@ public class AdminWorkOrderController {
         return Result.success(workOrderService.processWorkOrder(workOrderId, adminId, adminName, body));
     }
 
-    @ApiOperation("指派工单")
+    @ApiOperation(value = "指派工单", notes = "将工单分配给指定管理员处理。被指派人将在待办列表中看到该工单")
     @PutMapping("/{workOrderId}/assign")
     public Result<WorkOrderVO> assign(HttpServletRequest request,
                                        @ApiParam("工单ID") @PathVariable Long workOrderId,
@@ -80,7 +104,7 @@ public class AdminWorkOrderController {
         return Result.success(workOrderService.assignWorkOrder(workOrderId, adminId, adminName, assigneeId, assigneeName));
     }
 
-    @ApiOperation("添加备注")
+    @ApiOperation(value = "添加工单备注", notes = "在工单中追加备注信息，用于内部沟通和处理过程记录")
     @PostMapping("/{workOrderId}/comment")
     public Result<WorkOrderVO> addComment(HttpServletRequest request,
                                            @ApiParam("工单ID") @PathVariable Long workOrderId,
@@ -94,7 +118,7 @@ public class AdminWorkOrderController {
         return Result.success(workOrderService.addComment(workOrderId, adminId, adminName, content));
     }
 
-    @ApiOperation("按订单查工单数量")
+    @ApiOperation(value = "按订单查工单数量", notes = "返回指定订单关联的工单总数，用于订单详情页展示工单角标")
     @GetMapping("/count-by-order/{orderId}")
     public Result<Integer> countByOrder(@ApiParam("订单ID") @PathVariable Long orderId) {
         return Result.success(workOrderService.countByOrderId(orderId));

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java
index 0d65e46..e8684ef 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java
@@ -16,7 +16,7 @@ import java.util.List;
 /**
  * 相册内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  */
-@Api(tags = "【内部接口】小程序相册（Feign调用）")
+@Api(tags = "【内部接口】小程序相册（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/album")
 @RequiredArgsConstructor
@@ -24,13 +24,14 @@ public class InternalAlbumController {
 
     private final AlbumService albumService;
 
-    @ApiOperation("用户有相册的订单列表")
+    @ApiOperation(value = "用户有相册的订单列表", notes = "返回用户所有有相册文件夹的订单（含订单基本信息和相册封面），用于C端'我的相册'入口")
     @GetMapping("/orders")
     public Result<List<AlbumOrderVO>> listAlbumOrders(@RequestParam Long userId) {
         return Result.success(albumService.listUserAlbumOrders(userId));
     }
 
-    @ApiOperation("订单的文件夹列表")
+    @ApiOperation(value = "订单的文件夹列表",
+            notes = "内部服务间调用。返回指定用户指定订单下的相册文件夹列表，会校验订单归属权限。")
     @GetMapping("/order/{orderId}/folders")
     public Result<List<AlbumFolderVO>> listFolders(
             @RequestParam Long userId,
@@ -38,7 +39,10 @@ public class InternalAlbumController {
         return Result.success(albumService.listUserFolders(userId, orderId));
     }
 
-    @ApiOperation("文件夹下的文件列表")
+    @ApiOperation(value = "文件夹下的文件列表", notes = "**关联字典**：\n" +
+            "- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频\n" +
+            "- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @GetMapping("/folder/{folderId}/files")
     public Result<PageResult<AlbumFileVO>> listFiles(
             @RequestParam Long userId,
@@ -48,7 +52,7 @@ public class InternalAlbumController {
         return Result.success(albumService.listUserFiles(userId, folderId, page, size));
     }
 
-    @ApiOperation("获取文件下载链接")
+    @ApiOperation(value = "获取文件下载链接", notes = "生成带签名的临时下载URL（有效期1小时），用于C端用户下载原图/视频")
     @GetMapping("/file/{albumFileId}/download-url")
     public Result<String> getDownloadUrl(
             @RequestParam Long userId,

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java
index 0fd0c6a..110daf9 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java
@@ -11,7 +11,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "【内部接口】工作台统计（Feign调用）")
+@Api(tags = "【内部接口】工作台统计（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/order/dashboard")
 @RequiredArgsConstructor
@@ -19,7 +19,9 @@ public class InternalDashboardController {
 
     private final DashboardStatsService dashboardStatsService;
 
-    @ApiOperation("概览统计（支持定制师/全局，支持今日/本周/本月）")
+    @ApiOperation(value = "概览统计", notes = "返回订单量、成交金额、待处理订单数等概览数据。\n" +
+            "传customizerId则返回该定制师的数据，不传则返回全局数据。\n" +
+            "period支持: today(今日)、week(本周)、month(本月)")
     @GetMapping("/overview-stats")
     public Result<Map<String, Object>> getOverviewStats(
             @ApiParam("定制师ID，不传则为全局") @RequestParam(required = false) Long customizerId,
@@ -27,7 +29,9 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getOverviewStats(customizerId, period));
     }
 
-    @ApiOperation("待办分类汇总")
+    @ApiOperation(value = "待办分类汇总", notes = "按待办类型分组统计当前管理员的未完成待办数量，用于工作台待办卡片展示\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段中的待办类型key → 字典：order_todo_type（订单待办类型）")
     @GetMapping("/todo-summary")
     public Result<Map<String, Object>> getTodoSummary(
             @ApiParam("管理员ID") @RequestParam Long adminId,
@@ -35,7 +39,7 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getTodoSummary(adminId, roleKey));
     }
 
-    @ApiOperation("数据趋势（按天聚合）")
+    @ApiOperation(value = "数据趋势", notes = "按天聚合的订单量和金额趋势数据，用于折线图展示。支持最近7天或30天")
     @GetMapping("/trend")
     public Result<List<Map<String, Object>>> getTrend(
             @ApiParam("定制师ID，不传则为全局") @RequestParam(required = false) Long customizerId,
@@ -46,7 +50,9 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getTrend(customizerId, days));
     }
 
-    @ApiOperation("转化漏斗")
+    @ApiOperation(value = "转化漏斗", notes = "展示订单从创建→支付→确认→完成的转化率漏斗数据\n\n" +
+            "【关联字典】\n" +
+            "- 涉及字段 订单状态 → 字典：order_status（订单状态）")
     @GetMapping("/funnel")
     public Result<Map<String, Object>> getFunnel(
             @ApiParam("定制师ID，不传则为全局") @RequestParam(required = false) Long customizerId,
@@ -54,7 +60,10 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getFunnel(customizerId, period));
     }
 
-    @ApiOperation("即将出行列表")
+    @ApiOperation(value = "即将出行列表", notes = "返回最近即将出发的订单列表，按出发日期升序。用于工作台提醒关注即将出行的客户\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/upcoming-trips")
     public Result<List<Map<String, Object>>> getUpcomingTrips(
             @ApiParam("定制师ID，不传则为全局") @RequestParam(required = false) Long customizerId,
@@ -62,14 +71,14 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getUpcomingTrips(customizerId, limit));
     }
 
-    @ApiOperation("业绩排行（本月定制师排名）")
+    @ApiOperation(value = "业绩排行", notes = "按定制师维度统计成交金额排名，支持本周/本月周期。用于工作台排行榜展示")
     @GetMapping("/ranking")
     public Result<List<Map<String, Object>>> getRanking(
             @ApiParam("时间范围: month/week") @RequestParam(defaultValue = "month") String period) {
         return Result.success(dashboardStatsService.getRanking(period));
     }
 
-    @ApiOperation("日历事件")
+    @ApiOperation(value = "日历事件", notes = "返回指定月份的出发日期事件列表，用于工作台日历组件展示。每个事件包含订单基本信息")
     @GetMapping("/calendar-events")
     public Result<List<Map<String, Object>>> getCalendarEvents(
             @ApiParam("定制师ID") @RequestParam(required = false) Long customizerId,
@@ -78,14 +87,14 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getCalendarEvents(customizerId, year, month));
     }
 
-    @ApiOperation("财务统计")
+    @ApiOperation(value = "财务统计", notes = "返回收入、成本、利润等财务汇总数据，支持按时间周期统计")
     @GetMapping("/finance-stats")
     public Result<Map<String, Object>> getFinanceStats(
             @ApiParam("时间范围") @RequestParam(defaultValue = "today") String period) {
         return Result.success(dashboardStatsService.getFinanceStats(period));
     }
 
-    @ApiOperation("退款汇总")
+    @ApiOperation(value = "退款汇总", notes = "返回退款总额、退款笔数、退款率等汇总信息。传customizerId可查看单个定制师的退款数据")
     @GetMapping("/refund-summary")
     public Result<Map<String, Object>> getRefundSummary(
             @ApiParam("定制师ID") @RequestParam(required = false) Long customizerId) {

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java
index bb7a01e..cd52e45 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java
@@ -12,7 +12,7 @@ import org.springframework.web.bind.annotation.*;
 
 import java.util.Map;
 
-@Api(tags = "【内部接口】定制师订单（Feign调用）")
+@Api(tags = "【内部接口】定制师订单（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/order")
 @RequiredArgsConstructor
@@ -20,20 +20,29 @@ public class InternalDesignerOrderController {
 
     private final OrderService orderService;
 
-    @ApiOperation("获取定制师订单统计")
+    @ApiOperation(value = "获取定制师订单统计", notes = "返回指定定制师的订单统计数据（各状态数量、总金额等），用于定制师工作台概览\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段中的状态key → 字典：order_status（订单状态）")
     @GetMapping("/designer-stats")
     public Result<Map<String, Object>> getDesignerOrderStats(
             @ApiParam("定制师管理员ID") @RequestParam Long customizerId) {
         return Result.success(orderService.getDesignerOrderStats(customizerId));
     }
 
-    @ApiOperation("获取全局订单统计")
+    @ApiOperation(value = "获取全局订单统计", notes = "返回全平台的订单统计数据（各状态数量、总金额等），用于管理层工作台概览\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段中的状态key → 字典：order_status（订单状态）")
     @GetMapping("/global-stats")
     public Result<Map<String, Object>> getGlobalOrderStats() {
         return Result.success(orderService.getGlobalOrderStats());
     }
 
-    @ApiOperation("定制师订单列表")
+    @ApiOperation(value = "定制师订单列表", notes = "分页查询指定定制师负责的订单，支持按状态和关键词筛选\n\n" +
+            "【关联字典】\n" +
+            "- 筛选参数 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/designer-list")
     public Result<PageResult<OrderListVO>> listDesignerOrders(
             @ApiParam("定制师管理员ID") @RequestParam Long customizerId,

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java
index 97b3871..b1bf9e7 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java
@@ -15,7 +15,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.math.BigDecimal;
 import java.util.List;
 
-@Api(tags = "【内部接口】早鸟优惠（Feign调用）")
+@Api(tags = "【内部接口】早鸟优惠（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/early-bird")
 @RequiredArgsConstructor
@@ -23,14 +23,17 @@ public class InternalEarlyBirdController {
 
     private final EarlyBirdPlanService earlyBirdPlanService;
 
-    @ApiOperation("获取当前有效的早鸟优惠计划列表")
+    @ApiOperation(value = "获取当前有效的早鸟优惠计划列表", notes = "返回当前日期处于生效期内且已启用的早鸟计划，C端下单时展示可用优惠")
     @GetMapping("/active")
     public Result<List<EarlyBirdPlanVO>> listActivePlans() {
         List<EarlyBirdPlanVO> plans = earlyBirdPlanService.listActivePlans();
         return Result.success(plans);
     }
 
-    @ApiOperation("匹配最优早鸟优惠计划")
+    @ApiOperation(value = "匹配最优早鸟优惠计划", notes = "根据产品类型、出行人数、订单总价匹配优惠金额最大的早鸟计划。\n" +
+            "无匹配返回null。供下单时自动匹配调用\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 productType → 字典：product_type（产品类型）")
     @GetMapping("/match")
     public Result<EarlyBirdPlanVO> matchPlan(
             @RequestParam String productType,

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java
index e84a0e6..310b627 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java
@@ -15,7 +15,7 @@ import javax.validation.Valid;
  * C端发票内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "【内部接口】小程序发票（Feign调用）")
+@Api(tags = "【内部接口】小程序发票（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/invoice")
 @RequiredArgsConstructor
@@ -23,21 +23,33 @@ public class InternalInvoiceController {
 
     private final InvoiceService invoiceService;
 
-    @ApiOperation("申请开票")
+    @ApiOperation(value = "申请开票", notes = "用户对已支付订单申请开具电子发票。支持个人和企业抬头。\n" +
+            "同一订单只能开一次发票（可换开）\n\n" +
+            "**关联字典**：\n" +
+            "- invoice_title_type（抬头类型，请求/返回字段titleType）：PERSONAL=个人, COMPANY=企业\n" +
+            "- invoice_type（发票类型，返回字段invoiceType）：NORMAL=普通发票, SPECIAL=专用发票\n" +
+            "- invoice_status（发票状态，返回字段status）：PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废")
     @PostMapping("/apply")
     public Result<InvoiceVO> applyInvoice(@RequestParam Long userId,
                                           @Valid @RequestBody InvoiceApplyRequest request) {
         return Result.success(invoiceService.applyInvoice(userId, request));
     }
 
-    @ApiOperation("发票详情")
+    @ApiOperation(value = "发票详情", notes = "**关联字典**：\n" +
+            "- invoice_title_type（抬头类型，返回字段titleType）：PERSONAL=个人, COMPANY=企业\n" +
+            "- invoice_type（发票类型，返回字段invoiceType）：NORMAL=普通发票, SPECIAL=专用发票\n" +
+            "- invoice_status（发票状态，返回字段status）：PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废")
     @GetMapping("/{id}")
     public Result<InvoiceVO> getInvoiceDetail(@RequestParam Long userId,
                                               @PathVariable Long id) {
         return Result.success(invoiceService.getInvoiceDetail(userId, id));
     }
 
-    @ApiOperation("通过订单ID查询发票")
+    @ApiOperation(value = "通过订单ID查询发票", notes = "查询订单关联的发票信息。未开票时返回null\n\n" +
+            "**关联字典**：\n" +
+            "- invoice_title_type（抬头类型，返回字段titleType）：PERSONAL=个人, COMPANY=企业\n" +
+            "- invoice_type（发票类型，返回字段invoiceType）：NORMAL=普通发票, SPECIAL=专用发票\n" +
+            "- invoice_status（发票状态，返回字段status）：PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废")
     @GetMapping("/order/{orderId}")
     public Result<InvoiceVO> getInvoiceByOrderId(@RequestParam Long userId,
                                                   @PathVariable Long orderId) {

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java
index c27da3a..ec5f305 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java
@@ -24,7 +24,7 @@ import java.util.Map;
  * C端订单内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "【内部接口】小程序订单（Feign调用）")
+@Api(tags = "【内部接口】小程序订单（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/order")
 @RequiredArgsConstructor
@@ -32,7 +32,13 @@ public class InternalMpOrderController {
 
     private final OrderService orderService;
 
-    @ApiOperation("创建订单")
+    @ApiOperation(value = "创建订单", notes = "供BFF层调用的C端下单接口。创建后返回订单详情（含支付信息），前端可直接跳转支付\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 请求参数 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @PostMapping("/create")
     public Result<OrderDetailVO> createOrder(@RequestParam Long userId,
                                              @Valid @RequestBody CreateOrderRequest request) {
@@ -41,21 +47,32 @@ public class InternalMpOrderController {
         return Result.success(detail);
     }
 
-    @ApiOperation("订单列表")
+    @ApiOperation(value = "订单列表", notes = "【关联字典】\n" +
+            "- 筛选参数 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/list")
     public Result<PageResult<MpOrderListVO>> listOrders(@RequestParam Long userId,
                                                         MpOrderQueryRequest query) {
         return Result.success(orderService.listUserOrders(userId, query));
     }
 
-    @ApiOperation("订单详情")
+    @ApiOperation(value = "订单详情", notes = "【关联字典】\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）\n" +
+            "- 返回字段 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 返回字段 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 返回字段 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 timeline[].action → 字典：order_timeline_action（订单操作类型）")
     @GetMapping("/{orderId}")
     public Result<OrderDetailVO> getOrder(@RequestParam Long userId,
                                           @PathVariable Long orderId) {
         return Result.success(orderService.getUserOrderDetail(userId, orderId));
     }
 
-    @ApiOperation("取消订单")
+    @ApiOperation(value = "取消订单",
+            notes = "内部服务间调用，供BFF层调用的用户取消订单接口。仅允许取消待支付/已付定金状态的订单。")
     @PostMapping("/{orderId}/cancel")
     public Result<Void> cancelOrder(@RequestParam Long userId,
                                     @PathVariable Long orderId,
@@ -65,7 +82,8 @@ public class InternalMpOrderController {
         return Result.success();
     }
 
-    @ApiOperation("订单资源详情（按分类）")
+    @ApiOperation(value = "订单资源详情（按分类）",
+            notes = "内部服务间调用。解析订单的产品快照JSON，按资源类型分类提取资源详情（景区/酒店/活动/餐厅等），返回Map结构。")
     @GetMapping("/{orderId}/resources")
     public Result<Map<String, List<Map<String, Object>>>> getOrderResources(
             @RequestParam Long userId,
@@ -73,7 +91,7 @@ public class InternalMpOrderController {
         return Result.success(orderService.getOrderSnapshotResources(userId, orderId));
     }
 
-    @ApiOperation("通过联系人手机号+姓名查找订单（无需登录）")
+    @ApiOperation(value = "通过联系人手机号+姓名查找订单", notes = "无需登录。用于管理员代下单场景：管理员创建订单后用户通过手机号+姓名查找并绑定订单")
     @GetMapping("/lookup")
     public Result<java.util.List<MpOrderListVO>> lookupByContact(
             @RequestParam String contactPhone,
@@ -81,7 +99,8 @@ public class InternalMpOrderController {
         return Result.success(orderService.lookupByContact(contactPhone, contactName));
     }
 
-    @ApiOperation("绑定未绑定的订单（通过联系人手机号+姓名）")
+    @ApiOperation(value = "绑定未绑定的订单", notes = "将userId=NULL且联系人手机号+姓名匹配的订单绑定到当前用户。\n" +
+            "用于管理员代下单后用户登录自动关联订单。返回绑定的订单数量")
     @PostMapping("/bind-by-contact")
     public Result<Integer> bindByContact(@RequestParam Long userId,
                                          @Valid @RequestBody BindByContactRequest request) {
@@ -89,7 +108,7 @@ public class InternalMpOrderController {
         return Result.success(bindCount);
     }
 
-    @ApiOperation("客户同意解锁订单")
+    @ApiOperation(value = "客户同意解锁订单", notes = "管理员申请修改锁定订单后，C端用户确认同意解锁。解锁后管理员可重新编辑订单")
     @PostMapping("/{orderId}/approve-unlock")
     public Result<Void> approveUnlock(@RequestParam Long userId,
                                        @PathVariable Long orderId) {
@@ -103,13 +122,16 @@ public class InternalMpOrderController {
         return Result.success(orderService.getUpcomingDepartures(userId));
     }
 
-    @ApiOperation("各状态订单数量")
+    @ApiOperation(value = "各状态订单数量", notes = "返回用户各状态的订单数量Map，用于小程序订单页Tab角标显示\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段中的状态key → 字典：order_status（订单状态）")
     @GetMapping("/count")
     public Result<Map<String, Integer>> countByStatus(@RequestParam Long userId) {
         return Result.success(orderService.countByStatusForUser(userId));
     }
 
-    @ApiOperation("标记订单已评价（评价服务回调）")
+    @ApiOperation(value = "标记订单已评价", notes = "评价服务(review-service)在用户发布评价后回调此接口，将订单标记为已评价。\n" +
+            "标记后订单详情不再显示'去评价'按钮")
     @PutMapping("/{orderId}/mark-reviewed")
     public Result<Void> markReviewed(@PathVariable Long orderId) {
         orderService.markReviewed(orderId);
@@ -118,7 +140,13 @@ public class InternalMpOrderController {
 
     @ApiOperation(value = "用户修改订单", notes = "用户可修改出发日期和出行人，修改后重走内部流程（级联检测+价格重算）。" +
             "仅待支付/已付定金/已支付/已确认/待付尾款/待出发状态可修改。" +
-            "内部流程已启动的订单修改后会通知定制师，返回message中包含提示")
+            "内部流程已启动的订单修改后会通知定制师，返回message中包含提示\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 请求参数 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @PutMapping("/{orderId}/edit")
     public Result<OrderDetailVO> userEditOrder(@RequestParam Long userId,
                                                 @PathVariable Long orderId,

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java
index db0d1cc..8e4b990 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java
@@ -10,7 +10,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "【内部接口】小程序行程（Feign调用）")
+@Api(tags = "【内部接口】小程序行程（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/trip")
 @RequiredArgsConstructor
@@ -18,20 +18,29 @@ public class InternalMpTripController {
 
     private final TripService tripService;
 
-    @ApiOperation("行程列表")
+    @ApiOperation(value = "行程列表", notes = "返回用户所有有效订单的行程概要列表（已确认/待出发/出行中/已完成），按出发日期排序\n\n" +
+            "**关联字典**：\n" +
+            "- order_status（订单状态，返回字段status）：CONFIRMED=已确认, PENDING_DEPARTURE=待出发, TRAVELLING=出行中, COMPLETED=已完成\n" +
+            "- trip_phase（行程阶段，返回字段tripPhase）：BEFORE_START=出发前, IN_PROGRESS=出行中, ENDED=已结束")
     @GetMapping("/list")
     public Result<List<Map<String, Object>>> getTripList(@RequestParam Long userId) {
         return Result.success(tripService.getTripList(userId));
     }
 
-    @ApiOperation("行程详情")
+    @ApiOperation(value = "行程详情", notes = "返回订单的完整行程信息，包括每日行程节点、酒店安排、车辆安排、天气预报等\n\n" +
+            "**关联字典**：\n" +
+            "- order_status（订单状态，返回字段status）：CONFIRMED=已确认, PENDING_DEPARTURE=待出发, TRAVELLING=出行中, COMPLETED=已完成\n" +
+            "- trip_phase（行程阶段，返回字段tripPhase）：BEFORE_START=出发前, IN_PROGRESS=出行中, ENDED=已结束")
     @GetMapping("/{orderId}")
     public Result<Map<String, Object>> getTripDetail(@RequestParam Long userId,
                                                       @PathVariable Long orderId) {
         return Result.success(tripService.getTripDetail(userId, orderId));
     }
 
-    @ApiOperation("今日行程")
+    @ApiOperation(value = "今日行程", notes = "返回用户今天的行程安排。如果今天有正在出行的订单，返回当天的行程节点和安排；否则返回null\n\n" +
+            "**关联字典**：\n" +
+            "- order_status（订单状态，返回字段status）：CONFIRMED=已确认, PENDING_DEPARTURE=待出发, TRAVELLING=出行中, COMPLETED=已完成\n" +
+            "- trip_phase（行程阶段，返回字段tripPhase）：BEFORE_START=出发前, IN_PROGRESS=出行中, ENDED=已结束")
     @GetMapping("/today")
     public Result<Map<String, Object>> getTodayTrip(@RequestParam Long userId) {
         Map<String, Object> trip = tripService.getTodayTrip(userId);

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java
index 887cf27..38d3022 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java
@@ -12,7 +12,7 @@ import org.springframework.web.bind.annotation.*;
 
 import javax.validation.Valid;
 
-@Api(tags = "内部-订单统计")
+@Api(tags = "内部-订单统计", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/order")
 @RequiredArgsConstructor
@@ -21,19 +21,24 @@ public class InternalOrderStatsController {
     private final OrderService orderService;
     private final InvoiceService invoiceService;
 
-    @ApiOperation("获取产品已购出行人总数")
+    @ApiOperation(value = "获取产品已购出行人总数", notes = "统计指定产品的有效订单（非取消/非退款）出行人总数，用于产品详情页显示'已报名X人'")
     @GetMapping("/product-sold-count")
     public Result<Integer> getProductSoldCount(@RequestParam Long productId) {
         return Result.success(orderService.getProductSoldCount(productId));
     }
 
-    @ApiOperation("获取产品参与家庭数")
+    @ApiOperation(value = "获取产品参与家庭数", notes = "统计指定产品的有效订单数（一个订单视为一个家庭），用于产品详情页显示'已有X个家庭参与'")
     @GetMapping("/participant-family-count")
     public Result<Integer> getParticipantFamilyCount(@RequestParam Long productId) {
         return Result.success(orderService.getParticipantFamilyCount(productId));
     }
 
-    @ApiOperation("发票换开")
+    @ApiOperation(value = "发票换开", notes = "已开发票更换抬头信息（如个人改企业、更换公司名称等）。\n" +
+            "原发票作废，重新生成新发票\n\n" +
+            "**关联字典**：\n" +
+            "- invoice_title_type（抬头类型，请求/返回字段titleType）：PERSONAL=个人, COMPANY=企业\n" +
+            "- invoice_type（发票类型，返回字段invoiceType）：NORMAL=普通发票, SPECIAL=专用发票\n" +
+            "- invoice_status（发票状态，返回字段status）：PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废")
     @PostMapping("/invoice/reissue")
     public Result<InvoiceVO> reissueInvoice(@RequestBody @Valid InvoiceReissueRequest request) {
         return Result.success(invoiceService.reissueInvoice(request));

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java
index 2b39654..656382a 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java
@@ -11,7 +11,7 @@ import org.springframework.web.bind.annotation.*;
 /**
  * Internal API for payment service - 出行人验证
  */
-@Api(tags = "【内部接口】订单出行人（Feign调用）")
+@Api(tags = "【内部接口】订单出行人（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/order/traveler")
 @RequiredArgsConstructor
@@ -19,7 +19,11 @@ public class InternalOrderTravelerController {
 
     private final OrderTravelerService orderTravelerService;
 
-    @ApiOperation("验证订单出行人信息（供支付服务调用）")
+    @ApiOperation(value = "验证订单出行人信息", notes = "供支付服务在发起支付前调用。验证出行人数量是否满足订单要求、证件信息是否完整。\n" +
+            "返回验证结果，包含是否通过和具体错误信息列表\n\n" +
+            "【关联字典】\n" +
+            "- 涉及字段 出行人证件类型 → 字典：id_card_type（证件类型）\n" +
+            "- 涉及字段 出行人类型 → 字典：traveler_type（出行人类型）")
     @GetMapping("/validate/{orderId}")
     public Result<TravelerValidationDTO> validateTravelers(@PathVariable Long orderId) {
         TravelerValidationDTO validation = orderTravelerService.validateTravelers(orderId);

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java
index b708e85..be4a57c 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java
@@ -21,7 +21,7 @@ import java.util.stream.Collectors;
  * Internal endpoints for payment-service to call via Feign.
  * Not exposed through gateway, no authentication interceptor.
  */
-@Api(tags = "【内部接口】订单-支付/合同/保险（Feign调用）")
+@Api(tags = "【内部接口】订单-支付/合同/保险（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/order")
 @RequiredArgsConstructor
@@ -30,13 +30,16 @@ public class InternalPaymentOrderController {
     private final OrderService orderService;
     private final OrderTodoService orderTodoService;
 
-    @ApiOperation("获取订单支付信息")
+    @ApiOperation(value = "获取订单支付信息", notes = "供支付服务调用。返回订单号、应付金额、定金金额、已付金额等支付所需信息")
     @GetMapping("/{orderId}/pay-info")
     public Result<OrderPayInfoDTO> getPayInfo(@PathVariable Long orderId) {
         return Result.success(orderService.getPayInfo(orderId));
     }
 
-    @ApiOperation("通知支付成功")
+    @ApiOperation(value = "通知支付成功", notes = "支付服务收到微信支付回调后调用。更新订单状态(PENDING_PAY→DEPOSIT_PAID/PAID)和已付金额。\n" +
+            "幂等处理：重复调用不会重复更新\n\n" +
+            "【关联字典】\n" +
+            "- 涉及字段 订单status → 字典：order_status（订单状态）")
     @PostMapping("/payment-result")
     public Result<Void> notifyPaymentResult(@RequestBody PaymentResultDTO dto) {
         orderService.handlePaymentSuccess(dto.getOrderId(), dto.getPayType(),
@@ -44,14 +47,16 @@ public class InternalPaymentOrderController {
         return Result.success();
     }
 
-    @ApiOperation("通知退款成功")
+    @ApiOperation(value = "通知退款成功", notes = "支付服务收到微信退款回调后调用。更新订单已退金额，若全额退款则将订单状态改为已退款(REFUNDED)")
     @PostMapping("/refund-result")
     public Result<Void> notifyRefundResult(@RequestBody RefundResultDTO dto) {
         orderService.handleRefundSuccess(dto.getOrderId(), dto.getRefundAmount());
         return Result.success();
     }
 
-    @ApiOperation("获取订单基本信息(供合同服务调用)")
+    @ApiOperation(value = "获取订单基本信息(供合同服务调用)", notes = "【关联字典】\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/{orderId}/basic")
     public Result<Map<String, Object>> getOrderBasic(@PathVariable Long orderId) {
         OrderInfo order = orderService.getById(orderId);
@@ -80,7 +85,8 @@ public class InternalPaymentOrderController {
         return Result.success(data);
     }
 
-    @ApiOperation("获取用户订单ID列表(供合同服务调用)")
+    @ApiOperation(value = "获取用户订单ID列表(供合同服务调用)",
+            notes = "内部服务间调用。返回指定用户的所有订单ID列表，供合同服务查询用户关联合同时使用。")
     @GetMapping("/ids-by-user")
     public Result<List<Long>> getOrderIdsByUser(@RequestParam Long userId) {
         List<OrderInfo> orders = orderService.list(
@@ -94,7 +100,8 @@ public class InternalPaymentOrderController {
         return Result.success(ids);
     }
 
-    @ApiOperation("完成待办项(供合同/保险服务调用)")
+    @ApiOperation(value = "完成待办项(供合同/保险服务调用)",
+            notes = "内部服务间调用。合同服务签约完成或保险服务投保完成后调用此接口，将对应待办标记为已完成。系统自动检查是否所有必要待办已完成并推进内部流程。")
     @PostMapping("/{orderId}/complete-todo/{todoType}")
     public Result<Void> completeTodoByType(@PathVariable Long orderId,
                                             @PathVariable String todoType) {

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java
index 2464f08..f7c334f 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java
@@ -17,7 +17,7 @@ import org.springframework.web.bind.annotation.*;
 import javax.validation.Valid;
 import java.util.List;
 
-@Api(tags = "【内部接口】退款（Feign调用）")
+@Api(tags = "【内部接口】退款（Feign调用）", hidden = true)
 @RestController
 @RequiredArgsConstructor
 public class InternalRefundController {
@@ -27,20 +27,26 @@ public class InternalRefundController {
 
     // ==================== C-end (BFF → order-service) ====================
 
-    @ApiOperation(value = "退款金额预览", notes = "退款预览：根据退款政策和距出发天数，计算可退金额和退款比例")
+    @ApiOperation(value = "退款金额预览", notes = "退款预览：根据退款政策和距出发天数，计算可退金额和退款比例\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 refundType → 字典：refund_type（退款类型）")
     @GetMapping("/internal/mp/order/{orderId}/refund-preview")
     public Result<RefundPreviewVO> preview(@RequestParam("userId") Long userId,
                                             @PathVariable Long orderId) {
         return Result.success(refundApplicationService.previewRefund(orderId, userId));
     }
 
-    @ApiOperation("退款原因列表")
+    @ApiOperation(value = "退款原因列表（C端）", notes = "返回启用中的退款原因选项，供C端用户申请退款时选择\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 category → 字典：refund_reason_category（退款原因分类）")
     @GetMapping("/internal/mp/order/refund-reasons")
     public Result<List<RefundReasonVO>> listReasons() {
         return Result.success(refundReasonService.listReasons(true));
     }
 
-    @ApiOperation(value = "提交退款申请", notes = "退款申请流程：用户选择退款原因 → 填写退款说明 → 系统根据退款政策计算可退金额 → 生成退款申请(PENDING状态) → 等待管理员审批")
+    @ApiOperation(value = "提交退款申请", notes = "退款申请流程：用户选择退款原因 → 填写退款说明 → 系统根据退款政策计算可退金额 → 生成退款申请(PENDING状态) → 等待管理员审批\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @PostMapping("/internal/mp/order/{orderId}/refund")
     public Result<RefundApplicationVO> apply(@RequestParam("userId") Long userId,
                                               @RequestParam(value = "userName", required = false) String userName,
@@ -49,14 +55,18 @@ public class InternalRefundController {
         return Result.success(refundApplicationService.apply(orderId, userId, userName, request));
     }
 
-    @ApiOperation("退款申请详情")
+    @ApiOperation(value = "退款申请详情（C端）", notes = "返回退款申请信息，仅允许查看自己的退款申请\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @GetMapping("/internal/mp/order/refund/{applicationId}")
     public Result<RefundApplicationVO> getDetail(@RequestParam("userId") Long userId,
                                                    @PathVariable Long applicationId) {
         return Result.success(refundApplicationService.getDetailForUser(applicationId, userId));
     }
 
-    @ApiOperation("根据订单ID获取最新退款申请详情")
+    @ApiOperation(value = "根据订单ID获取最新退款申请", notes = "返回订单关联的最新一条退款申请，用于订单详情页展示退款进度。无退款申请时返回null\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @GetMapping("/internal/mp/order/{orderId}/refund-detail")
     public Result<RefundApplicationVO> getDetailByOrder(@RequestParam("userId") Long userId,
                                                           @PathVariable Long orderId) {
@@ -72,7 +82,7 @@ public class InternalRefundController {
         return Result.success(refundApplicationService.appeal(applicationId, userId, request));
     }
 
-    @ApiOperation("撤回退款申请")
+    @ApiOperation(value = "撤回退款申请", notes = "用户主动撤回退款申请。仅在待审批(PENDING)状态下可撤回。撤回后订单恢复原状态")
     @PostMapping("/internal/mp/order/refund/{applicationId}/cancel")
     public Result<Void> cancel(@RequestParam("userId") Long userId,
                                 @PathVariable Long applicationId) {
@@ -82,16 +92,18 @@ public class InternalRefundController {
 
     // ==================== Approval callback ====================
 
-    @ApiOperation("企微退款申诉审批结果回调")
+    @ApiOperation(value = "企微退款申诉审批结果回调", notes = "企微OA审批完成后由callback-service调用。\n" +
+            "审批通过则退款申请状态变为APPEAL_APPROVED，等待管理员确认实退金额后执行退款")
     @PostMapping("/internal/order/refund-appeal-result")
-    public Result<?> handleRefundAppealResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleRefundAppealResult(@RequestBody ApprovalResultDTO dto) {
         refundApplicationService.handleAppealResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();
     }
 
-    @ApiOperation("企微退款申请审批结果回调")
+    @ApiOperation(value = "企微退款申请审批结果回调", notes = "企微OA审批完成后由callback-service调用。\n" +
+            "审批通过则自动执行微信退款，审批拒绝则退款申请状态变为REJECTED")
     @PostMapping("/internal/order/refund-application-result")
-    public Result<?> handleRefundApplicationResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleRefundApplicationResult(@RequestBody ApprovalResultDTO dto) {
         refundApplicationService.handleApplicationApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();
     }

`hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java
index f29e8f9..9b3806e 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java
@@ -35,7 +35,13 @@ public class MpOrderController {
     private static final String ORDER_CREATE_DEDUP = "order:create:dedup:";
 
     @ApiOperation(value = "创建订单", notes = "C端下单流程：选择产品 → 填写联系人信息和出行人 → 系统报价 → 生成订单(PENDING_PAY状态)\n\n" +
-            "联系人和出行人是独立概念，联系人不必是出行人之一")
+            "联系人和出行人是独立概念，联系人不必是出行人之一\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 请求参数 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @PostMapping("/create")
     public Result<OrderInfo> createOrder(HttpServletRequest request,
                                            @ApiParam("创建订单请求") @Valid @RequestBody CreateOrderRequest createRequest) {
@@ -55,7 +61,12 @@ public class MpOrderController {
         }
     }
 
-    @ApiOperation("我的订单列表")
+    @ApiOperation(value = "我的订单列表", notes = "查询当前用户的订单列表，支持按状态筛选。\n" +
+            "用户需先完善个人资料(realName)后才能看到订单\n\n" +
+            "【关联字典】\n" +
+            "- 筛选参数 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/list")
     public Result<PageResult<MpOrderListVO>> listOrders(HttpServletRequest request,
                                                            @ApiParam("订单查询请求") MpOrderQueryRequest queryRequest) {
@@ -64,7 +75,15 @@ public class MpOrderController {
         return Result.success(result);
     }
 
-    @ApiOperation("订单详情")
+    @ApiOperation(value = "订单详情", notes = "获取订单完整信息。仅能查看自己的订单，查看他人订单会返回权限错误\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）\n" +
+            "- 返回字段 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 返回字段 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 返回字段 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 timeline[].action → 字典：order_timeline_action（订单操作类型）")
     @GetMapping("/{orderId}")
     public Result<OrderDetailVO> getOrder(HttpServletRequest request,
                                             @ApiParam("订单ID") @PathVariable Long orderId) {

`hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java` (M)

接口变更 diff：

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java
index 9e92157..1df079f 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java
@@ -12,7 +12,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "内部天气接口(Feign)")
+@Api(tags = "内部天气接口(Feign)", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/weather")
 @RequiredArgsConstructor
@@ -20,21 +20,21 @@ public class MpWeatherController {
 
     private final WeatherService weatherService;
 
-    @ApiOperation("获取订单行程天气")
+    @ApiOperation(value = "获取订单行程天气", notes = "根据订单行程中的城市和日期，批量查询天气信息。返回每天每个城市的天气数据列表")
     @GetMapping("/itinerary/{orderId}")
     public Result<List<Map<String, Object>>> getItineraryWeather(
             @ApiParam("订单ID") @PathVariable Long orderId) {
         return Result.success(weatherService.getItineraryWeather(orderId));
     }
 
-    @ApiOperation("获取指定城市实况天气")
+    @ApiOperation(value = "获取指定城市实况天气", notes = "调用高德天气API查询城市实时天气（温度、湿度、风向等），结果缓存30分钟")
     @GetMapping("/live")
     public Result<WeatherInfo> getLiveWeather(
             @ApiParam("城市名称") @RequestParam String city) {
         return Result.success(weatherService.getLiveWeather(city));
     }
 
-    @ApiOperation("获取指定城市天气预报")
+    @ApiOperation(value = "获取指定城市天气预报", notes = "调用高德天气API查询城市未来3天天气预报，结果缓存2小时")
     @GetMapping("/forecast")
     public Result<WeatherInfo> getForecastWeather(
             @ApiParam("城市名称") @RequestParam String city) {

`hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java` (M)

接口变更 diff：

diff --git a/hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java b/hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java
index 3392e72..10a9ea4 100644
--- a/hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java
+++ b/hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java
@@ -27,13 +27,13 @@ public class AdminPaymentController {
     private final RefundService refundService;
 
     @GetMapping("/list")
-    @ApiOperation(value = "支付交易列表", notes = "分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选")
+    @ApiOperation(value = "支付交易列表", notes = "分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选\n\n**关联字典**：\n- payment_mode：支付模式（列表筛选+显示）")
     public Result<PageResult<PaymentVO>> listTransactions(@ApiParam("支付查询条件") @Valid PaymentQueryRequest request) {
         return Result.success(paymentService.listTransactions(request));
     }
 
     @GetMapping("/{transactionId}")
-    @ApiOperation(value = "交易详情", notes = "获取单笔交易的完整信息，包含微信支付流水号")
+    @ApiOperation(value = "交易详情", notes = "获取单笔交易的完整信息，包含微信支付流水号\n\n**关联字典**：\n- payment_mode：支付模式（显示）")
     public Result<PaymentVO> getDetail(@ApiParam("交易ID") @PathVariable Long transactionId) {
         return Result.success(paymentService.getDetail(transactionId));
     }

`hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java` (M)

接口变更 diff：

diff --git a/hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java b/hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java
index d195a48..dbdfc84 100644
--- a/hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java
+++ b/hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java
@@ -25,14 +25,14 @@ import java.util.List;
 @RestController
 @RequestMapping("/internal/payment")
 @RequiredArgsConstructor
-@Api(tags = "【内部接口】支付（Feign调用）")
+@Api(tags = "【内部接口】支付（Feign调用）", hidden = true)
 public class InternalPaymentController {
 
     private final PaymentService paymentService;
     private final RefundService refundService;
 
     @PostMapping("/prepay")
-    @ApiOperation("Create prepay order (called by BFF)")
+    @ApiOperation(value = "创建预支付订单", notes = "由BFF层调用，向微信支付API发起预支付请求，返回前端调起支付所需的参数（prepay_id等）")
     public Result<PrepayResponse> prepay(
             @RequestParam("userId") Long userId,
             @Valid @RequestBody PrepayRequest request) {
@@ -41,7 +41,7 @@ public class InternalPaymentController {
     }
 
     @GetMapping("/status/{orderId}")
-    @ApiOperation("Query payment status (called by BFF)")
+    @ApiOperation(value = "查询支付状态", notes = "查询订单的支付状态，含用户权限校验（userId不匹配时拒绝访问）\n\n**关联字典**：\n- payment_status：支付状态（返回字段）")
     public Result<PaymentVO> getStatus(@RequestParam(value = "userId", required = false) Long userId,
                                         @PathVariable Long orderId) {
         PaymentVO vo = paymentService.getPaymentStatus(orderId);
@@ -53,7 +53,7 @@ public class InternalPaymentController {
     }
 
     @GetMapping("/transactions/{orderId}")
-    @ApiOperation("List all transactions for an order (called by BFF)")
+    @ApiOperation(value = "订单交易记录列表", notes = "查询指定订单的所有支付交易记录（含支付和退款），含用户权限校验\n\n**关联字典**：\n- payment_status：支付状态（返回字段）")
     public Result<List<PaymentVO>> listTransactions(@RequestParam(value = "userId", required = false) Long userId,
                                                      @PathVariable Long orderId) {
         List<PaymentVO> list = paymentService.listByOrder(orderId);
@@ -67,7 +67,7 @@ public class InternalPaymentController {
     }
 
     @PostMapping("/refund")
-    @ApiOperation("Create refund (called by order-service)")
+    @ApiOperation(value = "创建退款", notes = "由订单服务调用，向微信支付API发起退款请求。退款金额不能超过原支付金额，退款结果通过微信回调异步通知")
     public Result<RefundVO> createRefund(@Valid @RequestBody PaymentRefundRequest refundRequest) {
         RefundRequest request = new RefundRequest();
         request.setOrderId(refundRequest.getOrderId());

`hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java` (M)

接口变更 diff：

diff --git a/hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java b/hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java
index d950113..8b8106b 100644
--- a/hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java
+++ b/hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java
@@ -23,14 +23,14 @@ import java.util.Map;
 @RestController
 @RequestMapping("/pay/callback")
 @RequiredArgsConstructor
-@Api(tags = "【回调接口】支付回调")
+@Api(tags = "【回调接口】支付回调", hidden = true)
 public class PaymentCallbackController {
 
     private final PaymentService paymentService;
     private final RefundService refundService;
 
     @PostMapping("/notify/{mchId}")
-    @ApiOperation("支付成功回调")
+    @ApiOperation(value = "支付成功回调", notes = "微信支付成功后的异步通知回调（无需认证，通过微信签名验证安全性）。验证签名 → 更新支付状态 → 发送MQ消息通知订单服务")
     public ResponseEntity<Map<String, String>> payNotify(
             @PathVariable String mchId,
             HttpServletRequest request) {
@@ -49,7 +49,7 @@ public class PaymentCallbackController {
     }
 
     @PostMapping("/refund-notify/{mchId}")
-    @ApiOperation("退款回调")
+    @ApiOperation(value = "退款回调", notes = "微信退款结果的异步通知回调（无需认证，通过微信签名验证安全性）。验证签名 → 更新退款状态 → 发送MQ消息通知订单服务")
     public ResponseEntity<Map<String, String>> refundNotify(
             @PathVariable String mchId,
             HttpServletRequest request) {

`hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java
index 3d92709..5a21261 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java
@@ -21,7 +21,12 @@ public class DistrictController {
 
     private final AmapDistrictService amapDistrictService;
 
-    @ApiOperation("搜索行政区划（城市/区县）")
+    @ApiOperation(value = "搜索行政区划（城市/区县）",
+            notes = "通过高德地图 API 搜索行政区划，用于产品的出发城市和目的地城市选择。\n"
+                    + "输入关键词（如\"丽江\"、\"昆明\"），返回匹配的城市/区县列表，包含行政区划编码。\n\n"
+                    + "**关联字典**：\n"
+                    + "- cities（城市）：搜索结果可用于产品行程中的城市预览\n"
+                    + "- city（城市筛选）：搜索结果可用于资源面板城市筛选")
     @GetMapping("/search")
     public Result<List<AmapDistrictService.DistrictItem>> search(
             @ApiParam("搜索关键词") @RequestParam String keywords) {

`hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java
index b1bba5b..8e8827f 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java
@@ -21,13 +21,19 @@ public class FamilyController {
 
     private final ProductFamilyService familyService;
 
-    @ApiOperation("获取家庭分组列表")
+    @ApiOperation(value = "获取家庭分组列表",
+            notes = "获取产品的家庭分组列表，按排序序号升序。\n\n"
+                    + "**仅适用于 CUSTOM（定制）产品**。\n"
+                    + "家庭分组用于将定制产品的行程按家庭单位分配，每个家庭可以有不同的人数和行程安排。\n"
+                    + "行程节点通过 familyIds 字段关联到具体的家庭分组。")
     @GetMapping("/families")
     public Result<List<ProductFamilyVO>> listFamilies(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(familyService.listFamilies(productId));
     }
 
-    @ApiOperation("添加家庭分组")
+    @ApiOperation(value = "添加家庭分组",
+            notes = "为 CUSTOM 定制产品添加一个家庭分组，指定家庭名称和各类型人数。\n"
+                    + "添加后可在行程节点中关联此家庭，实现按家庭分配行程。")
     @PostMapping("/family")
     public Result<ProductFamilyVO> addFamily(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -35,7 +41,9 @@ public class FamilyController {
         return Result.success(familyService.addFamily(productId, request));
     }
 
-    @ApiOperation("更新家庭分组")
+    @ApiOperation(value = "更新家庭分组",
+            notes = "更新家庭分组的名称、各类型人数等信息。\n"
+                    + "**仅适用于 CUSTOM（定制）产品**。")
     @PutMapping("/family/{familyId}")
     public Result<ProductFamilyVO> updateFamily(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -44,7 +52,9 @@ public class FamilyController {
         return Result.success(familyService.updateFamily(familyId, request));
     }
 
-    @ApiOperation("删除家庭分组")
+    @ApiOperation(value = "删除家庭分组",
+            notes = "删除家庭分组。如果有行程节点通过 familyIds 关联了该分组，需要手动移除关联。\n"
+                    + "**仅适用于 CUSTOM（定制）产品**。")
     @DeleteMapping("/family/{familyId}")
     public Result<Void> deleteFamily(
             @ApiParam("产品ID") @PathVariable Long productId,

`hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java
index 9d4395e..6cc32f3 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java
@@ -32,20 +32,34 @@ public class FormulaController {
 
     // ===== Group endpoints =====
 
-    @ApiOperation("公式组列表")
+    @ApiOperation(value = "公式组列表",
+            notes = "获取定价公式组列表，可按产品类型筛选。\n\n"
+                    + "**公式引擎说明**：定价公式用于自动计算产品的成本价和售价。\n"
+                    + "每种产品类型可以有多个公式组，但同一时间只能有一个激活的公式组。\n"
+                    + "公式组包含多个步骤，按顺序执行，每步计算一个中间变量或最终结果。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，筛选条件）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/group/list")
     public Result<List<FormulaGroupVO>> listGroups(
             @RequestParam(required = false) String productType) {
         return Result.success(groupService.listGroups(productType));
     }
 
-    @ApiOperation("公式组详情")
+    @ApiOperation(value = "公式组详情",
+            notes = "获取公式组完整信息。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/group/{groupId}")
     public Result<FormulaGroupVO> getGroup(@PathVariable Long groupId) {
         return Result.success(groupService.getGroup(groupId));
     }
 
-    @ApiOperation("创建公式组")
+    @ApiOperation(value = "创建公式组",
+            notes = "创建一个新的定价公式组。创建后默认为未激活状态。\n\n"
+                    + "公式组编码（groupCode）在同一产品类型下必须唯一。\n"
+                    + "建议命名规范：{产品类型}_PRICING_V{版本号}，如 CORE_PRICING_V2。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，公式组所属类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PostMapping("/group")
     public Result<FormulaGroupVO> createGroup(@Valid @RequestBody FormulaGroupRequest request,
                                                HttpServletRequest httpRequest) {
@@ -53,21 +67,31 @@ public class FormulaController {
         return Result.success(groupService.createGroup(request, adminId));
     }
 
-    @ApiOperation("更新公式组")
+    @ApiOperation(value = "更新公式组",
+            notes = "更新公式组信息。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PutMapping("/group/{groupId}")
     public Result<FormulaGroupVO> updateGroup(@PathVariable Long groupId,
                                                @Valid @RequestBody FormulaGroupRequest request) {
         return Result.success(groupService.updateGroup(groupId, request));
     }
 
-    @ApiOperation("激活公式组")
+    @ApiOperation(value = "激活公式组",
+            notes = "激活指定公式组，同时自动停用同产品类型下的其他公式组。\n\n"
+                    + "同一产品类型下只能有一个激活的公式组，激活操作具有排他性。\n"
+                    + "激活后，该产品类型的自动成本计算将使用此公式组。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，同类型排他激活）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PutMapping("/group/{groupId}/activate")
     public Result<Void> activateGroup(@PathVariable Long groupId) {
         groupService.activateGroup(groupId);
         return Result.success();
     }
 
-    @ApiOperation("删除公式组")
+    @ApiOperation(value = "删除公式组",
+            notes = "删除公式组及其下所有步骤。\n"
+                    + "**限制**：已激活的公式组不能删除，需先激活其他公式组。")
     @DeleteMapping("/group/{groupId}")
     public Result<Void> deleteGroup(@PathVariable Long groupId) {
         groupService.deleteGroup(groupId);
@@ -76,25 +100,35 @@ public class FormulaController {
 
     // ===== Step endpoints =====
 
-    @ApiOperation("公式步骤列表")
+    @ApiOperation(value = "公式步骤列表",
+            notes = "获取公式组下所有步骤，按执行顺序（executionOrder）升序排列。\n"
+                    + "步骤按顺序依次执行，前一步的输出变量可作为后续步骤的输入。")
     @GetMapping("/group/{groupId}/steps")
     public Result<List<FormulaStepVO>> listSteps(@PathVariable Long groupId) {
         return Result.success(stepService.listSteps(groupId));
     }
 
-    @ApiOperation("公式步骤详情")
+    @ApiOperation(value = "公式步骤详情",
+            notes = "获取单个公式步骤的完整信息，包含表达式、输入/输出变量、执行顺序等。")
     @GetMapping("/step/{formulaId}")
     public Result<FormulaStepVO> getStep(@PathVariable Long formulaId) {
         return Result.success(stepService.getStep(formulaId));
     }
 
-    @ApiOperation("创建公式步骤")
+    @ApiOperation(value = "创建公式步骤",
+            notes = "在公式组中创建一个计算步骤。\n\n"
+                    + "**表达式语法**：使用 Aviator 表达式引擎，支持数学运算、条件判断、内置函数等。\n"
+                    + "示例：`baseCost = adultCount * adultUnitCost + childCount * childUnitCost`\n\n"
+                    + "**输入变量**：可引用公式变量表中定义的变量，或前置步骤的输出变量。\n"
+                    + "**输出变量**：每个步骤必须指定一个输出变量名，供后续步骤引用。")
     @PostMapping("/step")
     public Result<FormulaStepVO> createStep(@Valid @RequestBody FormulaStepRequest request) {
         return Result.success(stepService.createStep(request));
     }
 
-    @ApiOperation("更新公式步骤")
+    @ApiOperation(value = "更新公式步骤",
+            notes = "更新公式步骤的表达式、输入/输出变量等。\n"
+                    + "每次更新会自动保存一个版本快照，可通过版本历史接口查看和回滚。")
     @PutMapping("/step/{formulaId}")
     public Result<FormulaStepVO> updateStep(@PathVariable Long formulaId,
                                              @Valid @RequestBody FormulaStepRequest request,
@@ -103,27 +137,36 @@ public class FormulaController {
         return Result.success(stepService.updateStep(formulaId, request, adminId));
     }
 
-    @ApiOperation("启用/禁用公式步骤")
+    @ApiOperation(value = "启用/禁用公式步骤",
+            notes = "切换公式步骤的启用状态。\n"
+                    + "禁用的步骤在公式执行时会被跳过，不影响其他步骤的执行。\n"
+                    + "适用场景：临时跳过某个计算步骤进行调试或测试。")
     @PutMapping("/step/{formulaId}/toggle")
     public Result<Void> toggleStep(@PathVariable Long formulaId) {
         stepService.toggleStep(formulaId);
         return Result.success();
     }
 
-    @ApiOperation("删除公式步骤")
+    @ApiOperation(value = "删除公式步骤",
+            notes = "删除指定的公式步骤。删除后其他步骤的执行顺序不会自动调整。\n"
+                    + "**注意**：如果后续步骤引用了被删步骤的输出变量，执行时会报错。")
     @DeleteMapping("/step/{formulaId}")
     public Result<Void> deleteStep(@PathVariable Long formulaId) {
         stepService.deleteStep(formulaId);
         return Result.success();
     }
 
-    @ApiOperation("公式步骤版本历史")
+    @ApiOperation(value = "公式步骤版本历史",
+            notes = "获取公式步骤的所有历史版本列表，按版本号倒序。\n"
+                    + "每次更新步骤表达式会自动创建新版本，方便追溯和回滚。")
     @GetMapping("/step/{formulaId}/versions")
     public Result<List<FormulaVersionVO>> listVersions(@PathVariable Long formulaId) {
         return Result.success(stepService.listVersions(formulaId));
     }
 
-    @ApiOperation("回滚公式步骤到指定版本")
+    @ApiOperation(value = "回滚公式步骤到指定版本",
+            notes = "将公式步骤回滚到历史版本。\n"
+                    + "回滚操作会用历史版本的表达式、变量等覆盖当前内容，并创建一个新的版本记录。")
     @PutMapping("/step/{formulaId}/rollback/{versionNum}")
     public Result<FormulaStepVO> rollbackStep(@PathVariable Long formulaId,
                                                @PathVariable Integer versionNum,
@@ -134,7 +177,11 @@ public class FormulaController {
 
     // ===== Test endpoint =====
 
-    @ApiOperation("测试公式执行")
+    @ApiOperation(value = "测试公式执行",
+            notes = "使用自定义变量值测试公式组的执行结果，不影响任何业务数据。\n\n"
+                    + "传入公式组ID和测试变量（变量名→值的映射），返回每个步骤的执行结果。\n"
+                    + "适用于公式调试：验证表达式是否正确、计算结果是否符合预期。\n"
+                    + "如果某步骤执行出错，会在结果中标明错误信息。")
     @PostMapping("/test")
     public Result<FormulaTestResultVO> testFormulas(@Valid @RequestBody FormulaTestRequest request) {
         return Result.success(testService.testFormulas(request));
@@ -142,27 +189,41 @@ public class FormulaController {
 
     // ===== Var endpoints =====
 
-    @ApiOperation("公式变量列表")
+    @ApiOperation(value = "公式变量列表",
+            notes = "获取公式变量列表，可按变量分类筛选。\n\n"
+                    + "**变量分类**：\n"
+                    + "- INPUT：输入变量，从业务数据获取（如成人人数、资源单价）\n"
+                    + "- INTERMEDIATE：中间变量，由公式步骤计算得出\n"
+                    + "- OUTPUT：输出变量，最终报价结果（如总成本、售价）")
     @GetMapping("/var/list")
     public Result<List<FormulaVarVO>> listVars(
             @RequestParam(required = false) String category) {
         return Result.success(varService.listVars(category));
     }
 
-    @ApiOperation("创建公式变量")
+    @ApiOperation(value = "创建公式变量",
+            notes = "创建公式变量定义。变量名（varName）全局唯一，建议使用驼峰命名。\n"
+                    + "可指定适用的产品类型列表（productTypes），为空则适用于所有类型。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，变量适用范围）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PostMapping("/var")
     public Result<FormulaVarVO> createVar(@Valid @RequestBody FormulaVarRequest request) {
         return Result.success(varService.createVar(request));
     }
 
-    @ApiOperation("更新公式变量")

`hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java
index 7e553dc..ab7b818 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java
@@ -25,7 +25,16 @@ public class GroupBatchController {
 
     // ===== Batch CRUD =====
 
-    @ApiOperation("创建主批次")
+    @ApiOperation(value = "创建主批次",
+            notes = "为 GROUP（小蒙马拼团）产品创建一个团期主批次。\n\n"
+                    + "**仅适用于 GROUP 产品类型**。\n"
+                    + "每个批次有独立的出发日期、报名截止日期、人数上限。\n"
+                    + "创建后状态为 PENDING（待开放），需手动开启报名。\n\n"
+                    + "**批次状态流转**：PENDING → ENROLLING（报名中）→ CONFIRMED（已成团）→ CLOSED（已关闭）\n"
+                    + "任意报名状态均可被解散（DISBANDED）。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，仅限GROUP）：GROUP=小蒙马拼团\n"
+                    + "- batch_status（批次状态）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束")
     @PostMapping
     public Result<GroupTourBatchVO> createBatch(@PathVariable Long productId,
                                                 @Valid @RequestBody GroupBatchCreateRequest request,
@@ -34,7 +43,11 @@ public class GroupBatchController {
         return Result.success(batchService.createBatch(productId, request, adminId));
     }
 
-    @ApiOperation("创建子批次(溢出)")
+    @ApiOperation(value = "创建子批次(溢出)",
+            notes = "当主批次人数满员时，创建子批次接收溢出报名。\n\n"
+                    + "子批次共享主批次的出发日期和行程，但有独立的人数上限和报名人数。\n"
+                    + "适用场景：某团期特别火爆，需要扩容但希望分开管理。\n"
+                    + "子批次在列表中显示为主批次的子级节点。")
     @PostMapping("/{batchId}/sub-batch")
     public Result<GroupTourBatchVO> createSubBatch(@PathVariable Long productId,
                                                     @PathVariable Long batchId,
@@ -44,7 +57,9 @@ public class GroupBatchController {
         return Result.success(batchService.createSubBatch(batchId, request, adminId));
     }
 
-    @ApiOperation("更新批次")
+    @ApiOperation(value = "更新批次",
+            notes = "更新批次基本信息。仅传入需要修改的字段。\n"
+                    + "已有报名人员的批次修改人数上限时，不能低于已报名人数。")
     @PutMapping("/{batchId}")
     public Result<GroupTourBatchVO> updateBatch(@PathVariable Long productId,
                                                 @PathVariable Long batchId,
@@ -52,20 +67,30 @@ public class GroupBatchController {
         return Result.success(batchService.updateBatch(batchId, request));
     }
 
-    @ApiOperation("删除批次")
+    @ApiOperation(value = "删除批次",
+            notes = "删除批次（软删除）。\n"
+                    + "**限制**：已有报名人员的批次不能直接删除，需先解散批次。")
     @DeleteMapping("/{batchId}")
     public Result<Void> deleteBatch(@PathVariable Long productId, @PathVariable Long batchId) {
         batchService.deleteBatch(batchId);
         return Result.success();
     }
 
-    @ApiOperation("批次列表(树形)")
+    @ApiOperation(value = "批次列表(树形)",
+            notes = "获取产品所有批次，以树形结构返回（主批次包含子批次列表）。\n"
+                    + "按出发日期升序排列，包含每个批次的报名人数和剩余名额。\n\n"
+                    + "**关联字典**：\n"
+                    + "- batch_status（批次状态，返回字段）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束")
     @GetMapping("/list")
     public Result<List<GroupTourBatchVO>> listBatches(@PathVariable Long productId) {
         return Result.success(batchService.listBatches(productId));
     }
 
-    @ApiOperation("批次详情")
+    @ApiOperation(value = "批次详情",
+            notes = "获取单个批次的完整信息，包括批次基本信息、服务人员配置、套餐组合等。\n\n"
+                    + "**关联字典**：\n"
+                    + "- batch_status（批次状态）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束\n"
+                    + "- staff_type（人员类型，服务人员配置）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他")
     @GetMapping("/{batchId}")
     public Result<GroupTourBatchDetailVO> getBatchDetail(@PathVariable Long productId,
                                                          @PathVariable Long batchId) {
@@ -74,21 +99,33 @@ public class GroupBatchController {
 
     // ===== Status operations =====
 
-    @ApiOperation("开启报名(PENDING->ENROLLING)")
+    @ApiOperation(value = "开启报名(PENDING->ENROLLING)",
+            notes = "将批次从 PENDING 状态变更为 ENROLLING（报名中）。\n"
+                    + "开启后用户可在小程序端看到该团期并报名。\n"
+                    + "前提条件：产品必须已上架（PUBLISHED）。")
     @PutMapping("/{batchId}/open")
     public Result<Void> openEnrollment(@PathVariable Long productId, @PathVariable Long batchId) {
         batchService.openEnrollment(batchId);
         return Result.success();
     }
 
-    @ApiOperation("关闭报名(ENROLLING/CONFIRMED->CLOSED)")
+    @ApiOperation(value = "关闭报名(ENROLLING/CONFIRMED->CLOSED)",
+            notes = "关闭批次报名，不再接受新的报名。\n"
+                    + "已报名的订单不受影响，仅阻止新增报名。\n"
+                    + "适用于报名截止日期到达或手动提前关闭的场景。")
     @PutMapping("/{batchId}/close")
     public Result<Void> closeEnrollment(@PathVariable Long productId, @PathVariable Long batchId) {
         batchService.closeEnrollment(batchId);
         return Result.success();
     }
 
-    @ApiOperation("解散批次")
+    @ApiOperation(value = "解散批次",
+            notes = "解散批次并处理已报名的订单。\n\n"
+                    + "**重要**：解散操作会触发以下流程：\n"
+                    + "1. 批次状态变更为 DISBANDED\n"
+                    + "2. 通过 MQ 消息通知订单服务，自动取消该批次下的所有未完成订单\n"
+                    + "3. 已支付订单会触发退款流程\n\n"
+                    + "必须填写解散原因（如：报名人数不足、行程调整等）。")
     @PostMapping("/{batchId}/disband")
     public Result<Void> disbandBatch(@PathVariable Long productId,
                                       @PathVariable Long batchId,
@@ -103,7 +140,13 @@ public class GroupBatchController {
 
     // ===== Staff operations =====
 
-    @ApiOperation("保存服务人员(全量替换)")
+    @ApiOperation(value = "保存服务人员(全量替换)",
+            notes = "保存批次的服务人员配置，采用全量替换模式（先删后增）。\n\n"
+                    + "每次提交完整的人员列表，替换掉该批次原有的所有人员配置。\n"
+                    + "人员来源于资源服务的人员库，通过 staffId 关联。\n"
+                    + "**角色类型**：LEADER(领队)/PHOTOGRAPHER(摄影师)/DRIVER(司机)/OTHER(其他)\n\n"
+                    + "**关联字典**：\n"
+                    + "- staff_type（人员类型）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他")
     @PostMapping("/{batchId}/staff")
     public Result<List<GroupBatchStaffVO>> saveStaff(@PathVariable Long productId,
                                                      @PathVariable Long batchId,
@@ -111,14 +154,18 @@ public class GroupBatchController {
         return Result.success(staffService.saveStaff(batchId, productId, requests));
     }
 
-    @ApiOperation("服务人员列表")
+    @ApiOperation(value = "服务人员列表",
+            notes = "**关联字典**：\n"
+                    + "- staff_type（人员类型）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他")
     @GetMapping("/{batchId}/staff")
     public Result<List<GroupBatchStaffVO>> listStaff(@PathVariable Long productId,
                                                      @PathVariable Long batchId) {
         return Result.success(staffService.listStaff(batchId));
     }
 
-    @ApiOperation("从其他批次复制服务人员")
+    @ApiOperation(value = "从其他批次复制服务人员",
+            notes = "将源批次的服务人员配置复制到当前批次（全量替换当前批次已有人员）。\n"
+                    + "适用场景：多个团期使用相同的服务人员班底。")
     @PostMapping("/{batchId}/staff/copy-from/{sourceId}")
     public Result<List<GroupBatchStaffVO>> copyStaff(@PathVariable Long productId,
                                                      @PathVariable Long batchId,

`hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java
index 61d9a75..7a6ea65 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java
@@ -36,7 +36,7 @@ import java.util.Map;
  * C端产品内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "【内部接口】小程序产品（Feign调用）")
+@Api(tags = "【内部接口】小程序产品（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/product")
 @RequiredArgsConstructor
@@ -50,39 +50,56 @@ public class InternalMpProductController {
     private final ProductPriceCalendarMapper priceCalendarMapper;
     private final GroupTourBatchMapper groupTourBatchMapper;
 
-    @ApiOperation("产品列表")
+    @ApiOperation(value = "产品列表",
+            notes = "内部Feign接口，返回已上架产品列表。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，筛选+返回字段）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/list")
     public Result<PageResult<MpProductListVO>> listProducts(@Valid MpProductQueryRequest query) {
         return Result.success(productService.listPublishedProducts(query));
     }
 
-    @ApiOperation("产品详情")
+    @ApiOperation(value = "产品详情",
+            notes = "内部Feign接口，返回已上架产品详情。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态）：PUBLISHED=已上架\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @GetMapping("/{productId}")
     public Result<ProductVO> getProduct(@PathVariable Long productId) {
         return Result.success(productService.getPublishedProduct(productId));
     }
 
-    @ApiOperation("报价计算")
+    @ApiOperation(value = "报价计算",
+            notes = "内部服务间调用，供 hl-mp-service BFF 层 Feign 调用的报价计算接口。\n"
+                    + "计算逻辑与管理后台报价一致，根据日期和人数计算总价。")
     @PostMapping("/{productId}/quote")
     public Result<QuoteResultVO> calculateQuote(@PathVariable Long productId,
                                                @Valid @RequestBody QuoteRequest request) {
         return Result.success(quoteCalculatorService.calculateQuote(productId, request));
     }
 
-    @ApiOperation("产品线列表（活跃）")
+    @ApiOperation(value = "产品线列表（活跃）",
+            notes = "内部服务间调用，供 hl-mp-service 获取所有启用的产品线列表，用于小程序端筛选。")
     @GetMapping("/lines")
     public Result<List<ProductLineVO>> listActiveLines() {
         return Result.success(productLineService.listAllActive());
     }
 
-    @ApiOperation("推荐产品列表")
+    @ApiOperation(value = "推荐产品列表",
+            notes = "返回推荐的已上架产品。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，返回字段）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/recommend")
     public Result<List<MpProductListVO>> listRecommendProducts(
             @RequestParam(defaultValue = "6") int limit) {
         return Result.success(productService.listRecommendProducts(limit));
     }
 
-    @ApiOperation("C端价格日历")
+    @ApiOperation(value = "C端价格日历",
+            notes = "内部服务间调用，供 hl-mp-service 获取产品的价格日历数据。\n\n"
+                    + "可通过 startDate/endDate 限定查询范围，不传则返回今天及之后的所有可用日期。\n"
+                    + "返回每天的售价和库存信息，供小程序端日历选择器使用。")
     @GetMapping("/{productId}/price-calendar")
     public Result<List<Map<String, Object>>> getPriceCalendar(
             @PathVariable Long productId,
@@ -91,7 +108,10 @@ public class InternalMpProductController {
         return Result.success(priceCalendarService.getMpPriceCalendar(productId, startDate, endDate));
     }
 
-    @ApiOperation("产品最早可订日期")
+    @ApiOperation(value = "产品最早可订日期",
+            notes = "根据产品类型查询最早可预订日期。GROUP类型查批次出发日期，CORE/CUSTOM类型查价格日历。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，影响查询逻辑）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/earliest-booking-date")
     public Result<String> getEarliestBookingDate(@RequestParam Long productId) {
         Product product = productMapper.selectById(productId);
@@ -137,7 +157,10 @@ public class InternalMpProductController {
         }
     }
 
-    @ApiOperation("定制师产品统计（C端用）")
+    @ApiOperation(value = "定制师产品统计（C端用）",
+            notes = "统计指定定制师已发布的产品数量。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_status（产品状态，统计条件）：PUBLISHED=已上架")
     @GetMapping("/designer-stats")
     public Result<Map<String, Object>> getDesignerStats(@RequestParam Long customizerId) {
         long routeCount = productMapper.selectCount(

`hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java
index 978f513..7c0b2e7 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java
@@ -49,7 +49,7 @@ import java.util.stream.Collectors;
 @RestController
 @RequestMapping("/internal/product")
 @RequiredArgsConstructor
-@Api(tags = "【内部接口】产品（Feign调用）")
+@Api(tags = "【内部接口】产品（Feign调用）", hidden = true)
 public class InternalProductController {
 
     private final ProductStatusService productStatusService;
@@ -66,8 +66,12 @@ public class InternalProductController {
     private final GroupTourBatchMapper groupBatchMapper;
     private final ObjectMapper objectMapper;
 
+    @ApiOperation(value = "处理产品审批结果",
+            notes = "接收企微审批回调结果，更新产品状态。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_status（产品状态）：PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@Valid @RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@Valid @RequestBody ApprovalResultDTO dto) {
         try {
             productStatusService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
             return Result.success();
@@ -78,10 +82,12 @@ public class InternalProductController {
         }
     }
 
-    /**
-     * 获取产品详情（不过滤状态，供 order-service 创建订单时获取快照）
-     * 可选传入 date 参数，传入后会从资源价格日历查询各节点的成本价并填入快照
-     */
+    @ApiOperation(value = "获取产品详情（内部）",
+            notes = "不过滤状态，供 order-service 创建订单时获取快照。可选传入 date 参数查询各节点成本价。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @GetMapping("/{productId}/detail")
     public Result<ProductVO> getProductDetail(@PathVariable Long productId,
                                               @RequestParam(required = false) @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate date) {
@@ -91,19 +97,20 @@ public class InternalProductController {
         return Result.success(productService.getProduct(productId));
     }
 
-    /**
-     * 报价计算（供 order-service 创建订单时自动报价）
-     */
+    @ApiOperation(value = "报价计算（内部）",
+            notes = "供 order-service 创建订单时自动报价。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，影响计算逻辑）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PostMapping("/{productId}/quote")
     public Result<QuoteResultVO> calculateQuote(@PathVariable Long productId,
                                                @Valid @RequestBody QuoteRequest request) {
         return Result.success(quoteCalculatorService.calculateQuote(productId, request));
     }
 
-    /**
-     * 简单报价：直接从价格日历取售价 × 人数，不走资源价格计算。
-     * 小童 = 儿童售价 × 折扣比例，幼童 = 固定价格。
-     */
+    @ApiOperation(value = "简单报价（内部）",
+            notes = "直接从价格日历取售价乘以人数，不走资源价格计算。CUSTOM/ROUTE按整单，CORE/GROUP按人头。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，影响计算逻辑）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/{productId}/simple-quote")
     public Result<Map<String, Object>> simpleQuote(
             @PathVariable Long productId,
@@ -253,6 +260,10 @@ public class InternalProductController {
     /**
      * Deduct stock (optimistic lock: only succeeds if stock >= count)
      */
+    @ApiOperation(value = "扣减库存（内部）",
+            notes = "内部服务间调用，供 order-service 创建订单时扣减价格日历库存。\n\n"
+                    + "使用乐观锁机制：只有当库存 >= count 时才扣减成功。\n"
+                    + "扣减失败返回错误（库存不足），调用方需处理失败情况。")
     @PostMapping("/{productId}/deduct-stock")
     public Result<Void> deductStock(@PathVariable Long productId,
                                     @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") String date,
@@ -268,6 +279,9 @@ public class InternalProductController {
     /**
      * Restore stock (compensation for cancelled/expired orders)
      */
+    @ApiOperation(value = "恢复库存（内部）",
+            notes = "内部服务间调用，供 order-service 订单取消/过期时恢复价格日历库存。\n"
+                    + "用于补偿已扣减的库存，恢复数量不校验上限。")
     @PostMapping("/{productId}/restore-stock")
     public Result<Void> restoreStock(@PathVariable Long productId,
                                      @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") String date,
@@ -281,6 +295,9 @@ public class InternalProductController {
      * Get itinerary resources (SCENIC/ACTIVITY/HOTEL) for review service.
      * Returns deduplicated list of { resourceType, resourceId, resourceName }.
      */
+    @ApiOperation(value = "获取行程关联资源（内部）",
+            notes = "内部服务间调用，供 review-service 获取产品行程中关联的资源列表。\n\n"
+                    + "返回去重后的景区(SCENIC)、活动(ACTIVITY)、酒店(HOTEL)资源，用于评价时选择关联的资源对象。")
     @GetMapping("/{productId}/itinerary-resources")
     public Result<List<Map<String, Object>>> getItineraryResources(@PathVariable Long productId) {
         // Allowed resource types for review
@@ -310,9 +327,11 @@ public class InternalProductController {
         return Result.success(result);
     }
 
-    /**
-     * 变更定制产品状态（供 order-service 调用：下单→ORDERED / 取消→COMPLETED）
-     */
+    @ApiOperation(value = "变更定制产品状态（内部）",
+            notes = "供 order-service 调用：下单时 COMPLETED→ORDERED，取消时 ORDERED→COMPLETED。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，仅限CUSTOM）：CUSTOM=定制产品\n"
+                    + "- product_status（产品状态）：COMPLETED=已完成, ORDERED=已下单")
     @PutMapping("/{productId}/custom-status")
     public Result<Void> changeCustomProductStatus(@PathVariable Long productId,
                                                    @RequestParam String targetStatus) {
@@ -339,6 +358,10 @@ public class InternalProductController {
     /**
      * Enroll participants (optimistic lock on batch).
      */
+    @ApiOperation(value = "报名入团（内部）",
+            notes = "内部服务间调用，供 order-service 下单时增加批次已报名人数。\n\n"
+                    + "使用乐观锁机制：只有当剩余名额 >= peopleCount 时才报名成功。\n"
+                    + "报名成功后自动检查是否满员（FULL）或达到成团条件（CONFIRMED）。")
     @PostMapping("/batch/{batchId}/enroll")
     public Result<Void> enrollBatch(@PathVariable Long batchId,
                                      @RequestParam @Min(1) int peopleCount) {
@@ -349,6 +372,9 @@ public class InternalProductController {
     /**
      * Unenroll participants (compensation for cancellation).
      */
+    @ApiOperation(value = "退出报名（内部）",
+            notes = "内部服务间调用，供 order-service 订单取消/退款时减少批次已报名人数。\n"
+                    + "用于补偿已报名的人数，恢复剩余名额。")
     @PostMapping("/batch/{batchId}/unenroll")
     public Result<Void> unenrollBatch(@PathVariable Long batchId,
                                        @RequestParam @Min(1) int peopleCount) {
@@ -356,9 +382,10 @@ public class InternalProductController {
         return Result.success();
     }
 
-    /**
-     * Get batch info (for order snapshot).
-     */
+    @ApiOperation(value = "批次信息（内部）",
+            notes = "供 order-service 创建订单时获取批次快照。\n\n"
+                    + "**关联字典**：\n"
+                    + "- batch_status（批次状态，返回字段）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束")
     @GetMapping("/batch/{batchId}/info")
     public Result<Map<String, Object>> getBatchInfo(@PathVariable Long batchId) {
         GroupTourBatch batch = groupTourBatchService.getBatchById(batchId);
@@ -385,6 +412,10 @@ public class InternalProductController {
     /**
      * GROUP quote: returns adult/child dynamic pricing for a batch.
      */
+    @ApiOperation(value = "GROUP产品报价（内部）",
+            notes = "内部服务间调用，供 order-service 和 mp-service 获取 GROUP 产品按套餐组合的报价。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，仅限GROUP）：GROUP=小蒙马拼团")
     @GetMapping("/{productId}/group-quote")
     public Result<GroupQuoteResultVO> getGroupQuote(@PathVariable Long productId,
                                                      @RequestParam Long batchId,
@@ -395,6 +426,9 @@ public class InternalProductController {
     /**
      * C-end calendar data for GROUP products.
      */
+    @ApiOperation(value = "团期日历数据（内部）",
+            notes = "内部服务间调用，供小程序端展示 GROUP 产品的团期日历。\n\n"
+                    + "返回可报名批次的出发日期、状态、剩余名额等信息，用于日历选择器展示。")
     @GetMapping("/{productId}/batches/calendar")
     public Result<List<GroupBatchCalendarVO>> getBatchesCalendar(@PathVariable Long productId) {
         return Result.success(groupTourBatchService.listCalendar(productId));
@@ -403,6 +437,9 @@ public class InternalProductController {
     /**
      * C-end combo list for a batch (套餐列表).
      */
+    @ApiOperation(value = "批次套餐列表（内部）",
+            notes = "内部服务间调用，供小程序端展示 GROUP 产品批次下的套餐组合列表。\n\n"
+                    + "每个套餐包含成人/儿童人数搭配、售价、原价、库存和已售数量。")
     @GetMapping("/batch/{batchId}/combos")
     public Result<List<Map<String, Object>>> listBatchCombos(@PathVariable Long batchId) {
         List<GroupBatchCombo> combos = comboMapper.selectList(
@@ -431,7 +468,9 @@ public class InternalProductController {
 
     // ===== 定制师内部接口 =====
 
-    @ApiOperation("获取定制师已发布产品ID列表")
+    @ApiOperation(value = "获取定制师已发布产品ID列表",
+            notes = "**关联字典**：\n"
+                    + "- product_status（产品状态，筛选条件）：PUBLISHED=已上架")
     @GetMapping("/designer-published-ids")
     public Result<List<String>> getDesignerPublishedProductIds(@RequestParam Long createBy) {
         List<Long> ids = productService.getDesignerPublishedProductIds(createBy);
@@ -439,19 +478,28 @@ public class InternalProductController {
         return Result.success(strIds);
     }
 
-    @ApiOperation("获取全局产品统计")

`hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java
index f813a83..7ea5e3b 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java
@@ -28,7 +28,10 @@ public class ItineraryController {
 
     // ========================= Day =========================
 
-    @ApiOperation("更新行程天")
+    @ApiOperation(value = "更新行程天",
+            notes = "更新指定天的行程信息，如当天主题、概述等。\n"
+                    + "行程天在创建产品时根据 tripDays 自动生成，不支持单独增删，只能更新。\n"
+                    + "dayNumber 从 1 开始，对应第几天的行程。")
     @PutMapping("/item/{productId}/day/{dayNumber}")
     public Result<ItineraryDayVO> updateDay(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -37,7 +40,9 @@ public class ItineraryController {
         return Result.success(dayService.updateDay(productId, dayNumber, request));
     }
 
-    @ApiOperation("获取行程天列表")
+    @ApiOperation(value = "获取行程天列表",
+            notes = "获取产品所有行程天的信息，按 dayNumber 升序排列。\n"
+                    + "每一天包含当天主题、概述等信息，不包含节点详情（节点通过单独接口获取）。")
     @GetMapping("/item/{productId}/days")
     public Result<List<ItineraryDayVO>> listDays(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(dayService.listDays(productId));
@@ -45,7 +50,14 @@ public class ItineraryController {
 
     // ========================= Node =========================
 
-    @ApiOperation("添加行程节点")
+    @ApiOperation(value = "添加行程节点",
+            notes = "在指定天添加一个行程节点。节点是行程的最小单元，可关联资源服务中的景区、酒店、活动等。\n\n"
+                    + "**节点类型**：TRANSPORT(交通)/SCENIC(景区)/DINING(餐饮)/ACTIVITY(活动)/"
+                    + "PHOTOGRAPHY(摄影)/HOTEL(酒店)/FREE(自由活动)/CUSTOM(自定义)\n\n"
+                    + "**CUSTOM 定制产品特有**：可通过 familyIds 指定节点所属的家庭分组，实现按家庭分配行程。\n"
+                    + "新建节点自动追加到当天最后位置，可通过排序接口调整顺序。\n\n"
+                    + "**关联字典**：\n"
+                    + "- city（城市，资源面板筛选用）：用于在添加节点时按城市筛选可选资源")
     @PostMapping("/item/{productId}/day/{dayNumber}/node")
     public Result<ItineraryNodeVO> createNode(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -54,7 +66,12 @@ public class ItineraryController {
         return Result.success(nodeService.createNode(productId, dayNumber, request));
     }
 
-    @ApiOperation("更新行程节点")
+    @ApiOperation(value = "更新行程节点",
+            notes = "更新行程节点信息，仅传入需要修改的字段。\n"
+                    + "可修改节点名称、时间、关联资源、图片、描述等。\n\n"
+                    + "**关联字典**：\n"
+                    + "- city（城市）：资源面板城市筛选\n"
+                    + "- cities（城市ID映射）：城市名称预览")
     @PutMapping("/node/{nodeId}")
     public Result<ItineraryNodeVO> updateNode(
             @ApiParam("行程节点ID") @PathVariable Long nodeId,
@@ -62,14 +79,17 @@ public class ItineraryController {
         return Result.success(nodeService.updateNode(nodeId, request));
     }
 
-    @ApiOperation("删除行程节点")
+    @ApiOperation(value = "删除行程节点",
+            notes = "删除指定行程节点，同天其他节点的排序自动调整。")
     @DeleteMapping("/node/{nodeId}")
     public Result<Void> deleteNode(@ApiParam("行程节点ID") @PathVariable Long nodeId) {
         nodeService.deleteNode(nodeId);
         return Result.success();
     }
 
-    @ApiOperation("行程节点拖拽排序")
+    @ApiOperation(value = "行程节点拖拽排序",
+            notes = "重新排列指定天的所有行程节点顺序。前端拖拽排序后，将新的节点ID顺序全量提交。\n"
+                    + "nodeIds 列表中的顺序即为新的排序顺序（从上到下）。")
     @PutMapping("/item/{productId}/day/{dayNumber}/nodes/sort")
     public Result<Void> sortNodes(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -79,13 +99,17 @@ public class ItineraryController {
         return Result.success();
     }
 
-    @ApiOperation("复制行程节点")
+    @ApiOperation(value = "复制行程节点",
+            notes = "复制指定节点到同一天的末尾位置，包括节点的所有属性（名称、资源关联、图片等）。\n"
+                    + "适用场景：同一天有相似的行程安排时快速复制。")
     @PostMapping("/node/{nodeId}/copy")
     public Result<ItineraryNodeVO> copyNode(@ApiParam("行程节点ID") @PathVariable Long nodeId) {
         return Result.success(nodeService.copyNode(nodeId));
     }
 
-    @ApiOperation("移动行程节点到其他天")
+    @ApiOperation(value = "移动行程节点到其他天",
+            notes = "将节点从当前天移动到目标天的末尾位置。\n"
+                    + "移动后原天和目标天的节点排序自动调整。")
     @PutMapping("/node/{nodeId}/move")
     public Result<ItineraryNodeVO> moveNode(
             @ApiParam("行程节点ID") @PathVariable Long nodeId,
@@ -93,7 +117,12 @@ public class ItineraryController {
         return Result.success(nodeService.moveNode(nodeId, request.getTargetDayNumber()));
     }
 
-    @ApiOperation("获取某天的节点列表")
+    @ApiOperation(value = "获取某天的节点列表",
+            notes = "获取指定天的所有行程节点，按排序顺序返回。\n"
+                    + "每个节点包含类型、名称、时间、关联资源信息、图片等完整数据。\n\n"
+                    + "**关联字典**：\n"
+                    + "- city（城市）：资源面板城市筛选\n"
+                    + "- cities（城市ID映射）：城市名称预览")
     @GetMapping("/item/{productId}/day/{dayNumber}/nodes")
     public Result<List<ItineraryNodeVO>> listNodes(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -103,7 +132,10 @@ public class ItineraryController {
 
     // ========================= Hotel =========================
 
-    @ApiOperation("添加每日住宿")
+    @ApiOperation(value = "添加每日住宿",
+            notes = "为指定天添加住宿安排，关联资源服务中的酒店和房型。\n"
+                    + "每天可以有多个住宿选项（如不同档次），参与成本自动计算。\n"
+                    + "住宿费用会体现在价格日历的成本计算中。")
     @PostMapping("/item/{productId}/day/{dayNumber}/hotel")
     public Result<DayHotelVO> addHotel(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -112,7 +144,8 @@ public class ItineraryController {
         return Result.success(hotelService.addHotel(productId, dayNumber, request));
     }
 
-    @ApiOperation("更新每日住宿")
+    @ApiOperation(value = "更新每日住宿",
+            notes = "更新住宿记录的酒店、房型、数量等信息。")
     @PutMapping("/hotel/{id}")
     public Result<DayHotelVO> updateHotel(
             @ApiParam("住宿记录ID") @PathVariable Long id,
@@ -120,14 +153,16 @@ public class ItineraryController {
         return Result.success(hotelService.updateHotel(id, request));
     }
 
-    @ApiOperation("删除每日住宿")
+    @ApiOperation(value = "删除每日住宿",
+            notes = "删除指定住宿记录。删除后该天的住宿成本会从报价中移除。")
     @DeleteMapping("/hotel/{id}")
     public Result<Void> deleteHotel(@ApiParam("住宿记录ID") @PathVariable Long id) {
         hotelService.deleteHotel(id);
         return Result.success();
     }
 
-    @ApiOperation("获取某天的住宿列表")
+    @ApiOperation(value = "获取某天的住宿列表",
+            notes = "获取指定天的所有住宿安排，包含酒店名称、房型、数量等信息。")
     @GetMapping("/item/{productId}/day/{dayNumber}/hotels")
     public Result<List<DayHotelVO>> listHotels(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -137,7 +172,9 @@ public class ItineraryController {
 
     // ========================= Dining =========================
 
-    @ApiOperation("添加每日餐厅推荐")
+    @ApiOperation(value = "添加每日餐厅推荐",
+            notes = "为指定天添加餐饮推荐，关联资源服务中的餐厅。\n"
+                    + "用于展示当天的用餐安排，可按早/午/晚分类。")
     @PostMapping("/item/{productId}/day/{dayNumber}/dining")
     public Result<DiningOptionVO> addDiningOption(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -146,7 +183,8 @@ public class ItineraryController {
         return Result.success(diningOptionService.addDiningOption(productId, dayNumber, request));
     }
 
-    @ApiOperation("更新餐饮推荐")
+    @ApiOperation(value = "更新餐饮推荐",
+            notes = "更新餐饮推荐的餐厅、用餐类型（早/午/晚）、描述等信息。")
     @PutMapping("/dining/{id}")
     public Result<DiningOptionVO> updateDiningOption(
             @ApiParam("餐饮推荐ID") @PathVariable Long id,
@@ -154,7 +192,8 @@ public class ItineraryController {
         return Result.success(diningOptionService.updateDiningOption(id, request));
     }
 
-    @ApiOperation("获取某天的餐厅推荐列表")
+    @ApiOperation(value = "获取某天的餐厅推荐列表",
+            notes = "获取指定天的所有餐饮推荐，包含餐厅名称、用餐类型、描述等信息。")
     @GetMapping("/item/{productId}/day/{dayNumber}/dining")
     public Result<List<DiningOptionVO>> listDining(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -162,7 +201,8 @@ public class ItineraryController {
         return Result.success(diningOptionService.listDiningOptions(productId, dayNumber));
     }
 
-    @ApiOperation("删除餐饮推荐")
+    @ApiOperation(value = "删除餐饮推荐",
+            notes = "删除指定的餐饮推荐记录。")
     @DeleteMapping("/dining/{id}")
     public Result<Void> deleteDiningOption(@ApiParam("餐饮推荐ID") @PathVariable Long id) {
         diningOptionService.deleteDiningOption(id);
@@ -171,7 +211,9 @@ public class ItineraryController {
 
     // ========================= Supplies =========================
 
-    @ApiOperation("添加物资配品")
+    @ApiOperation(value = "添加物资配品",
+            notes = "为产品添加物资配品（如帐篷、睡袋、登山杖等），关联资源服务中的物资。\n"

`hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java
index 526bc16..94a6723 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java
@@ -31,19 +31,33 @@ public class MpProductController {
     private final ProductService productService;
     private final QuoteCalculatorService quoteCalculatorService;
 
-    @ApiOperation("产品列表")
+    @ApiOperation(value = "产品列表（C端）",
+            notes = "小程序端产品列表接口，仅返回已上架（PUBLISHED）的产品。\n\n"
+                    + "支持按产品类型、季节、行程天数、目的地、产品线、支付模式、定制师等筛选。\n"
+                    + "默认按 sortOrder 排序，也可按价格或行程天数排序。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，筛选条件）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/list")
     public Result<PageResult<MpProductListVO>> listProducts(@ApiParam("产品查询请求") @Valid MpProductQueryRequest query) {
         return Result.success(productService.listPublishedProducts(query));
     }
 
-    @ApiOperation("产品详情")
+    @ApiOperation(value = "产品详情（C端）",
+            notes = "小程序端产品详情接口，仅返回已上架（PUBLISHED）的产品。\n"
+                    + "包含完整的行程信息、定价配置、费用说明、创作者寄语等。\n"
+                    + "未上架的产品会返回 404 错误。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @GetMapping("/{productId}")
     public Result<ProductVO> getProduct(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(productService.getPublishedProduct(productId));
     }
 
-    @ApiOperation("报价计算")
+    @ApiOperation(value = "报价计算（C端）",
+            notes = "小程序端报价计算接口，根据用户选择的日期和人数计算总价。\n"
+                    + "内部会校验产品是否存在且已上架。\n"
+                    + "详细计算逻辑参见管理后台的报价计算接口说明。")
     @PostMapping("/{productId}/quote")
     public Result<QuoteResultVO> calculateQuote(
             @ApiParam("产品ID") @PathVariable Long productId,

`hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java
index cdd0cb8..1599755 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java
@@ -28,7 +28,18 @@ public class PricingController {
 
     // ========== 定价规则 ==========
 
-    @ApiOperation("保存定价规则")
+    @ApiOperation(value = "保存定价规则",
+            notes = "保存或更新产品的定价配置（一个产品仅一条定价记录，重复调用为覆盖更新）。\n\n"
+                    + "**定价模式**：\n"
+                    + "- AUTO：自动计算，通过公式引擎根据行程资源价格自动测算成本和售价\n"
+                    + "- MANUAL：手动定价，直接在价格日历中手动设置每日价格\n"
+                    + "- CUSTOM：定制定价，设置整单总价（customTotalPrice），不按人头\n\n"
+                    + "**利润模式**（AUTO 模式下生效）：\n"
+                    + "- FIXED：固定金额加价，售价 = 成本 + profitAmount\n"
+                    + "- PERCENT：百分比加价，售价 = 成本 × (1 + markupPercent/100)\n\n"
+                    + "**支付方式**：FULL=全款支付，DEPOSIT=定金+尾款（需设置 depositRatio 或 depositAmount）\n\n"
+                    + "**关联字典**：\n"
+                    + "- vehicle_type（车型）：费用配置中车辆相关成本计算")
     @PostMapping("/pricing")
     public Result<ProductPricingVO> savePricing(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -36,7 +47,11 @@ public class PricingController {
         return Result.success(pricingService.savePricing(productId, request));
     }
 
-    @ApiOperation("获取定价规则")
+    @ApiOperation(value = "获取定价规则",
+            notes = "获取产品的定价配置，包括定价模式、利润设置、儿童/婴儿价格、支付方式等。\n"
+                    + "如果产品尚未设置定价规则，返回 null。\n\n"
+                    + "**关联字典**：\n"
+                    + "- vehicle_type（车型）：费用配置中车辆相关成本显示")
     @GetMapping("/pricing")
     public Result<ProductPricingVO> getPricing(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(pricingService.getPricing(productId));
@@ -44,7 +59,11 @@ public class PricingController {
 
     // ========== 价格日历 ==========
 
-    @ApiOperation("获取月度价格日历")
+    @ApiOperation(value = "获取月度价格日历",
+            notes = "获取指定月份的价格日历数据列表。\n\n"
+                    + "每条数据包含：日期、成人售价/成本价、儿童售价/成本价、库存、状态（OPEN/CLOSED）等。\n"
+                    + "**CORE/GROUP 产品**：价格为单人价格，按人头 × 价格计算总价。\n"
+                    + "**CUSTOM/ROUTE 产品**：价格为整单总价，不乘以人头数。")
     @GetMapping("/price-calendar")
     public Result<List<PriceCalendarVO>> getMonthCalendar(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -53,7 +72,10 @@ public class PricingController {
         return Result.success(calendarService.getMonthCalendar(productId, year, month));
     }
 
-    @ApiOperation("设置单日价格")
+    @ApiOperation(value = "设置单日价格",
+            notes = "设置或更新指定日期的价格和库存。如果该日期已有记录则更新，否则新建。\n\n"
+                    + "可设置成人售价/成本价、儿童售价/成本价、库存数量、状态（OPEN/CLOSED）。\n"
+                    + "状态为 CLOSED 的日期不会出现在小程序端的可选日期中。")
     @PostMapping("/price-calendar")
     public Result<PriceCalendarVO> setDayPrice(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -61,7 +83,11 @@ public class PricingController {
         return Result.success(calendarService.setDayPrice(productId, request));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格",
+            notes = "批量设置日期范围内的价格和库存，支持按星期筛选。\n\n"
+                    + "指定 startDate 和 endDate 日期范围，可选 selectedWeekdays 过滤星期几。\n"
+                    + "示例：设置5月1日-5月31日的工作日（周一到周五=[1,2,3,4,5]）价格。\n"
+                    + "selectedWeekdays 为空时，范围内所有日期都会被设置。")
     @PostMapping("/price-calendar/batch")
     public Result<List<PriceCalendarVO>> batchSetPrices(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -69,7 +95,13 @@ public class PricingController {
         return Result.success(calendarService.batchSetPrices(productId, request));
     }
 
-    @ApiOperation("测算预览（不写入数据库）")
+    @ApiOperation(value = "测算预览（不写入数据库）",
+            notes = "根据行程中的资源价格日历，自动计算指定日期的成本价和售价，仅预览不保存。\n\n"
+                    + "用于在设置价格日历前预览自动计算的结果。\n"
+                    + "计算逻辑：汇总当天所有行程节点关联资源的价格 → 应用公式引擎 → 加上利润。\n"
+                    + "GROUP 产品需要传 adultCount 参数（影响均摊计算）。\n\n"
+                    + "**关联字典**：\n"
+                    + "- vehicle_type（车型）：车辆费用成本测算")
     @PostMapping("/price-calendar/calc-preview")
     public Result<CalcPreviewVO> calcPreview(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -77,13 +109,21 @@ public class PricingController {
         return Result.success(calendarService.calcPreview(productId, request));
     }
 
-    @ApiOperation("重新测算所有自动测算日期的价格")
+    @ApiOperation(value = "重新测算所有自动测算日期的价格",
+            notes = "重新计算价格日历中所有 costAutoCalc=true 的日期的成本价和售价。\n\n"
+                    + "适用场景：资源价格调整后，批量刷新所有自动计算的价格日历。\n"
+                    + "返回更新的日期数量和详情。手动设置的价格（costAutoCalc=false）不受影响。")
     @PostMapping("/price-calendar/recalculate")
     public Result<java.util.Map<String, Object>> recalculate(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(calendarService.recalculateAll(productId));
     }
 
-    @ApiOperation("自动计算成本并同步到价格日历")
+    @ApiOperation(value = "自动计算成本并同步到价格日历",
+            notes = "根据出发日期和人数，自动计算成本并将结果写入价格日历。\n\n"
+                    + "与测算预览不同，此接口会实际更新价格日历数据。\n"
+                    + "计算逻辑：查询各资源的价格日历 → 汇总成本 → 应用公式和利润规则 → 写入结果。\n\n"
+                    + "**关联字典**：\n"
+                    + "- vehicle_type（车型）：车辆费用成本计算")
     @PostMapping("/price-calendar/auto-calc")
     public Result<QuoteResultVO> autoCalcCost(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -100,7 +140,10 @@ public class PricingController {
 
     // ========== 费用包含/不包含 ==========
 
-    @ApiOperation("添加费用项")
+    @ApiOperation(value = "添加费用项",
+            notes = "添加产品的费用包含/不包含说明项。\n\n"
+                    + "用于在产品详情页展示\"费用包含\"和\"费用不包含\"信息。\n"
+                    + "仅用于前端展示，不参与报价计算。")
     @PostMapping("/cost-item")
     public Result<ProductCostItemVO> addCostItem(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -108,7 +151,8 @@ public class PricingController {
         return Result.success(costItemService.addCostItem(productId, request));
     }
 
-    @ApiOperation("更新费用项")
+    @ApiOperation(value = "更新费用项",
+            notes = "更新费用包含/不包含说明项的内容。仅用于前端展示，不参与报价计算。")
     @PutMapping("/cost-item/{itemId}")
     public Result<ProductCostItemVO> updateCostItem(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -117,7 +161,8 @@ public class PricingController {
         return Result.success(costItemService.updateCostItem(itemId, request));
     }
 
-    @ApiOperation("删除费用项")
+    @ApiOperation(value = "删除费用项",
+            notes = "删除费用包含/不包含说明项。")
     @DeleteMapping("/cost-item/{itemId}")
     public Result<Void> deleteCostItem(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -126,7 +171,8 @@ public class PricingController {
         return Result.success();
     }
 
-    @ApiOperation("获取费用项列表")
+    @ApiOperation(value = "获取费用项列表",
+            notes = "获取产品的所有费用包含/不包含说明项列表。")
     @GetMapping("/cost-items")
     public Result<List<ProductCostItemVO>> listCostItems(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(costItemService.listCostItems(productId));
@@ -134,7 +180,10 @@ public class PricingController {
 
     // ========== 额外成本关联 ==========
 
-    @ApiOperation("添加额外成本关联")
+    @ApiOperation(value = "添加额外成本关联",
+            notes = "关联资源服务中的费用项（cost_item）到产品，参与成本自动计算。\n\n"
+                    + "额外成本是指不包含在行程节点中、但需要计入总成本的费用。\n"
+                    + "例如：导游服务费、保险费、通讯费等固定运营开支。")
     @PostMapping("/extra-cost")
     public Result<ProductExtraCostVO> addExtraCost(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -142,7 +191,8 @@ public class PricingController {
         return Result.success(extraCostService.addExtraCost(productId, request));
     }
 
-    @ApiOperation("更新额外成本关联")
+    @ApiOperation(value = "更新额外成本关联",
+            notes = "更新额外成本关联的费用项、数量等信息。修改后会影响成本自动计算结果。")
     @PutMapping("/extra-cost/{ecId}")
     public Result<ProductExtraCostVO> updateExtraCost(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -151,7 +201,8 @@ public class PricingController {
         return Result.success(extraCostService.updateExtraCost(ecId, request));
     }
 
-    @ApiOperation("删除额外成本关联")
+    @ApiOperation(value = "删除额外成本关联",
+            notes = "删除额外成本关联记录。删除后该费用项不再计入成本自动计算。")
     @DeleteMapping("/extra-cost/{ecId}")
     public Result<Void> removeExtraCost(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -160,7 +211,8 @@ public class PricingController {
         return Result.success();
     }
 
-    @ApiOperation("获取额外成本关联列表")
+    @ApiOperation(value = "获取额外成本关联列表",
+            notes = "获取产品关联的所有额外成本项列表，包含费用项名称、金额等信息。")
     @GetMapping("/extra-costs")
     public Result<List<ProductExtraCostVO>> listExtraCosts(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(extraCostService.listExtraCosts(productId));
@@ -168,7 +220,10 @@ public class PricingController {

`hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java
index bc250d7..5f48dff 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java
@@ -28,7 +28,20 @@ public class ProductController {
     private final ProductStatusService productStatusService;
     private final RouteMapService routeMapService;
 
-    @ApiOperation("创建产品（草稿）")
+    @ApiOperation(value = "创建产品（草稿）",
+            notes = "创建一个新产品，初始状态为 DRAFT（草稿）。\n\n"
+                    + "**产品类型说明**：\n"
+                    + "- CORE：核心产品，标准旅游产品，支持上架/下架审批流程\n"
+                    + "- GROUP：小蒙马拼团，需配合团期批次管理，按人头计价\n"
+                    + "- CUSTOM：定制产品，由定制师为客户量身定制，按单计价\n"
+                    + "- ROUTE：线路产品，预设线路模板，按单计价\n\n"
+                    + "**注意事项**：\n"
+                    + "- 创建后需依次完善行程、定价、价格日历等信息\n"
+                    + "- CUSTOM/ROUTE 产品的价格日历存储的是整单总价，不按人头乘算\n"
+                    + "- GROUP 产品需额外创建团期批次才能报名\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @PostMapping
     public Result<ProductVO> createProduct(
             @ApiParam("创建产品请求") @Valid @RequestBody ProductCreateRequest request,
@@ -37,13 +50,28 @@ public class ProductController {
         return Result.success(productService.createProduct(request, adminId));
     }
 
-    @ApiOperation("获取产品详情")
+    @ApiOperation(value = "获取产品详情",
+            notes = "获取产品完整信息，包括基本信息、行程天列表、定价配置、费用项等。\n"
+                    + "返回数据包含关联的行程节点资源详情，适用于产品编辑页面。\n"
+                    + "不过滤产品状态，所有状态的产品都可查看。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @GetMapping("/{productId}")
     public Result<ProductVO> getProduct(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(productService.getProduct(productId));
     }
 
-    @ApiOperation("更新产品")
+    @ApiOperation(value = "更新产品",
+            notes = "更新产品基本信息，仅传入需要修改的字段，未传字段不会被覆盖。\n\n"
+                    + "**权限说明**：\n"
+                    + "- 普通管理员只能编辑自己创建的产品\n"
+                    + "- SUPER_ADMIN 可编辑所有产品\n\n"
+                    + "**注意**：行程、定价、价格日历等通过各自独立的接口管理，不在此接口中处理。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @PutMapping("/{productId}")
     public Result<ProductVO> updateProduct(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -54,7 +82,10 @@ public class ProductController {
         return Result.success(productService.updateProduct(productId, request, adminId, role));
     }
 
-    @ApiOperation("删除产品")
+    @ApiOperation(value = "删除产品",
+            notes = "软删除产品（设置 deleted_at 字段）。\n\n"
+                    + "**权限说明**：普通管理员只能删除自己创建的产品，SUPER_ADMIN 可删除所有产品。\n"
+                    + "**限制**：已上架（PUBLISHED）的产品不能直接删除，需先下架。")
     @DeleteMapping("/{productId}")
     public Result<Void> deleteProduct(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -65,17 +96,33 @@ public class ProductController {
         return Result.success();
     }
 
-    @ApiOperation("产品列表")
+    @ApiOperation(value = "产品列表",
+            notes = "分页查询产品列表，支持多维度筛选和排序。\n\n"
+                    + "**权限说明**：\n"
+                    + "- 普通管理员只能看到自己创建的产品\n"
+                    + "- SUPER_ADMIN 可看到所有产品\n\n"
+                    + "**筛选条件**：关键词（名称/副标题模糊匹配）、产品类型、状态、文件夹、产品线、季节、行程天数。\n"
+                    + "支持多状态筛选（statuses 字段，逗号分隔）。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，筛选条件）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态，筛选条件+返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单")
     @GetMapping("/list")
     public Result<PageResult<ProductListVO>> listProducts(
             @ApiParam("产品查询请求") @Valid ProductQueryRequest query,
             HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);
-        boolean isSuperAdmin = "SUPER_ADMIN".equals(httpRequest.getAttribute("role"));
-        return Result.success(productService.listProducts(query, adminId, isSuperAdmin));
+        String role = (String) httpRequest.getAttribute("role");
+        boolean canViewAll = "SUPER_ADMIN".equals(role) || "CUSTOMER_SERVICE".equals(role);
+        return Result.success(productService.listProducts(query, adminId, canViewAll));
     }
 
-    @ApiOperation("复制产品")
+    @ApiOperation(value = "复制产品",
+            notes = "深度复制产品，包括行程天、行程节点、定价配置、住宿、餐饮、物资、人员配置等所有关联数据。\n\n"
+                    + "复制后的产品状态为 DRAFT，名称自动添加\"(副本)\"后缀。\n"
+                    + "适用场景：基于已有产品快速创建新产品。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，返回字段）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态，复制后固定为 DRAFT）")
     @PostMapping("/{productId}/copy")
     public Result<ProductVO> copyProduct(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -84,7 +131,9 @@ public class ProductController {
         return Result.success(productService.copyProduct(productId, adminId));
     }
 
-    @ApiOperation("移动产品到文件夹")
+    @ApiOperation(value = "移动产品到文件夹",
+            notes = "将产品移动到指定文件夹，或移出文件夹（folderId 传空字符串或 null）。\n"
+                    + "文件夹用于组织管理产品，不影响产品的业务逻辑。")
     @PutMapping("/{productId}/move")
     public Result<Void> moveProduct(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -95,7 +144,10 @@ public class ProductController {
         return Result.success();
     }
 
-    @ApiOperation("生成定制产品分享链接")
+    @ApiOperation(value = "生成定制产品分享链接",
+            notes = "为 CUSTOM（定制）产品生成小程序分享链接，用于定制师发送给客户查看方案。\n\n"
+                    + "**限制**：仅 CUSTOM 类型且状态为 COMPLETED 的产品可生成。\n"
+                    + "**权限**：普通管理员只能为自己创建的产品生成链接，SUPER_ADMIN 不受限制。")
     @PostMapping("/{productId}/share-link")
     public Result<ShareLinkVO> generateShareLink(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -105,7 +157,10 @@ public class ProductController {
         return Result.success(productService.generateShareLink(productId, adminId, role));
     }
 
-    @ApiOperation("手动生成路径图")
+    @ApiOperation(value = "手动生成路径图",
+            notes = "根据产品行程节点的经纬度信息，调用地图API生成行程路径图。\n\n"
+                    + "通常在行程编辑完成后手动触发，生成结果为 OSS 图片 URL。\n"
+                    + "如果行程节点没有经纬度信息，则无法生成路径图。")
     @PostMapping("/{productId}/generate-route-map")
     public Result<String> generateRouteMap(@ApiParam("产品ID") @PathVariable Long productId) {
         try {
@@ -116,7 +171,20 @@ public class ProductController {
         }
     }
 
-    @ApiOperation("产品状态变更（上架/下架等）")
+    @ApiOperation(value = "产品状态变更（上架/下架/完成）",
+            notes = "根据产品类型，状态流转规则不同：\n\n"
+                    + "**核心产品(CORE) / 小蒙马(GROUP)**：支持上架/下架，需企微审批\n"
+                    + "- DRAFT → PENDING_REVIEW → REVIEWED → PUBLISHED（上架）\n"
+                    + "- PUBLISHED → UNPUBLISHED（下架）\n"
+                    + "- UNPUBLISHED → PUBLISHED（重新上架）\n"
+                    + "- REJECTED → DRAFT（驳回后重新编辑）\n\n"
+                    + "**定制产品(CUSTOM)**：仅支持完成，无上架/下架概念\n"
+                    + "- DRAFT → COMPLETED（定制师完成设计）\n"
+                    + "- COMPLETED → ORDERED（客户下单，系统自动变更）\n"
+                    + "- ORDERED → COMPLETED（订单取消/退款后回退）\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，影响状态流转规则）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态，请求+返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单")
     @PutMapping("/{productId}/status")
     public Result<Void> changeStatus(
             @ApiParam("产品ID") @PathVariable Long productId,

`hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java
index 2562b23..2b69413 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java
@@ -23,7 +23,9 @@ public class ProductFolderController {
 
     private final ProductFolderService folderService;
 
-    @ApiOperation("创建文件夹")
+    @ApiOperation(value = "创建文件夹",
+            notes = "创建产品文件夹，用于组织管理产品。支持多级目录结构。\n"
+                    + "文件夹归属于创建人，普通管理员只能看到自己的文件夹。")
     @PostMapping
     public Result<ProductFolderVO> createFolder(
             @ApiParam("创建文件夹请求") @Valid @RequestBody FolderCreateRequest request,
@@ -33,7 +35,9 @@ public class ProductFolderController {
         return Result.success(folderService.createFolder(request, adminId, ownerName));
     }
 
-    @ApiOperation("更新文件夹")
+    @ApiOperation(value = "更新文件夹",
+            notes = "更新文件夹名称等信息。\n"
+                    + "**权限说明**：普通管理员只能更新自己创建的文件夹，SUPER_ADMIN 可更新任何文件夹。")
     @PutMapping("/{folderId}")
     public Result<ProductFolderVO> updateFolder(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -44,7 +48,9 @@ public class ProductFolderController {
         return Result.success(folderService.updateFolder(folderId, request, adminId, isSuperAdmin));
     }
 
-    @ApiOperation("删除文件夹")
+    @ApiOperation(value = "删除文件夹",
+            notes = "删除文件夹。如果文件夹下有产品，产品会自动移到根目录（folderId 置空）。\n"
+                    + "普通管理员只能删除自己的文件夹，SUPER_ADMIN 可删除任何文件夹。")
     @DeleteMapping("/{folderId}")
     public Result<Void> deleteFolder(@ApiParam("文件夹ID") @PathVariable Long folderId, HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);
@@ -53,7 +59,10 @@ public class ProductFolderController {
         return Result.success();
     }
 
-    @ApiOperation("获取文件夹树")
+    @ApiOperation(value = "获取文件夹树",
+            notes = "获取当前用户可见的文件夹树形结构。\n"
+                    + "普通管理员只能看到自己创建的文件夹，SUPER_ADMIN 可看到所有文件夹。\n"
+                    + "返回结构为嵌套的树形列表，包含每个文件夹的子文件夹。")
     @GetMapping("/tree")
     public Result<List<ProductFolderVO>> getFolderTree(HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);

`hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java
index 28d7d17..13683ab 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java
@@ -25,7 +25,9 @@ public class ProductLineController {
 
     private final ProductLineService lineService;
 
-    @ApiOperation("创建产品线")
+    @ApiOperation(value = "创建产品线",
+            notes = "创建产品线，用于对产品进行业务分类（如：亲子游、蜜月游、探险游等）。\n"
+                    + "产品线在小程序端可作为筛选条件，帮助用户快速找到感兴趣的产品类别。")
     @PostMapping
     public Result<ProductLineVO> createLine(
             @ApiParam("创建产品线请求") @Valid @RequestBody LineCreateRequest request,
@@ -34,7 +36,8 @@ public class ProductLineController {
         return Result.success(lineService.createLine(request, adminId));
     }
 
-    @ApiOperation("更新产品线")
+    @ApiOperation(value = "更新产品线",
+            notes = "更新产品线名称、描述、状态等信息。")
     @PutMapping("/{lineId}")
     public Result<ProductLineVO> updateLine(
             @ApiParam("产品线ID") @PathVariable Long lineId,
@@ -42,26 +45,31 @@ public class ProductLineController {
         return Result.success(lineService.updateLine(lineId, request));
     }
 
-    @ApiOperation("删除产品线")
+    @ApiOperation(value = "删除产品线",
+            notes = "删除产品线（软删除）。已关联产品的产品线仍可删除，但关联产品的产品线字段不会被清空。")
     @DeleteMapping("/{lineId}")
     public Result<Void> deleteLine(@ApiParam("产品线ID") @PathVariable Long lineId) {
         lineService.deleteLine(lineId);
         return Result.success();
     }
 
-    @ApiOperation("产品线详情")
+    @ApiOperation(value = "产品线详情",
+            notes = "获取指定产品线的完整信息。")
     @GetMapping("/{lineId}")
     public Result<ProductLineVO> getLine(@ApiParam("产品线ID") @PathVariable Long lineId) {
         return Result.success(lineService.getLine(lineId));
     }
 
-    @ApiOperation("产品线列表（分页）")
+    @ApiOperation(value = "产品线列表（分页）",
+            notes = "分页查询产品线列表，支持按名称关键词筛选。")
     @GetMapping("/list")
     public Result<PageResult<ProductLineVO>> listLines(@ApiParam("产品线查询请求") @Valid LineQueryRequest query) {
         return Result.success(lineService.listLines(query));
     }
 
-    @ApiOperation("所有启用的产品线")
+    @ApiOperation(value = "所有启用的产品线",
+            notes = "获取所有启用状态的产品线，不分页。\n"
+                    + "适用于产品编辑时的产品线下拉选择，以及小程序端的筛选项。")
     @GetMapping("/active")
     public Result<List<ProductLineVO>> listAllActive() {
         return Result.success(lineService.listAllActive());

`hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java` (M)

接口变更 diff：

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java
index b6676e4..81f33f0 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java
@@ -23,7 +23,18 @@ public class QuoteController {
     private final QuoteCalculatorService quoteCalculatorService;
     private final CostCalculationService costCalculationService;
 
-    @ApiOperation("计算报价")
+    @ApiOperation(value = "计算报价",
+            notes = "根据出发日期和人数组合，计算产品的完整报价。\n\n"
+                    + "**计算流程**：\n"
+                    + "1. 从价格日历获取指定日期的单价\n"
+                    + "2. 按人数类型分别计算：成人 × 成人价、儿童 × 儿童价\n"
+                    + "3. 小童按儿童价 × 折扣比例（childDiscountPercent）计算\n"
+                    + "4. 婴儿使用固定价格（babyPrice）\n"
+                    + "5. 儿童加床（childNeedBed=true）额外加收 childWithBed 费用\n\n"
+                    + "**CUSTOM/ROUTE 产品**：价格日历存的是整单总价，不按人头乘算。\n"
+                    + "**GROUP 产品**：建议使用 group-quote 接口，支持套餐组合报价。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，影响计算逻辑）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PostMapping("/quote")
     public Result<QuoteResultVO> calculateQuote(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -31,7 +42,13 @@ public class QuoteController {
         return Result.success(quoteCalculatorService.calculateQuote(productId, request));
     }
 
-    @ApiOperation("GROUP产品报价（按组合）")
+    @ApiOperation(value = "GROUP产品报价（按套餐组合）",
+            notes = "为 GROUP（小蒙马拼团）产品按团期批次和套餐组合计算报价。\n\n"
+                    + "GROUP 产品的价格由批次下的套餐组合（combo）决定，不同组合有不同的成人/儿童人数搭配和价格。\n"
+                    + "传入 batchId 指定团期批次，adultCount 用于匹配合适的套餐组合。\n\n"
+                    + "**与普通报价的区别**：普通报价从价格日历取单价，GROUP 报价从套餐组合取打包价。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，仅限GROUP）：GROUP=小蒙马拼团")
     @GetMapping("/group-quote")
     public Result<GroupQuoteResultVO> calculateGroupQuote(
             @ApiParam("产品ID") @PathVariable Long productId,

`hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java
index ab64e9e..4015f1e 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java
@@ -26,7 +26,7 @@ public class ActivityController {
 
     private final ActivityService activityService;
 
-    @ApiOperation("创建游玩项目")
+    @ApiOperation(value = "创建游玩项目", notes = "新建游玩项目资源（如漂流、骑行、篝火晚会等），初始状态为草稿(status=0)。需通过「提交启用/禁用审批」走企微审批后上架。支持按项收费(PER_ITEM)和按人收费(PER_PERSON)两种计费方式。\n\n**关联字典**：\n- activity_category：活动分类（表单选择）\n- activity_billing_type：计费方式（表单选择）")
     @PostMapping("/item")
     public Result<ActivityVO> createActivity(
             @ApiParam("游玩项目创建请求") @Valid @RequestBody ActivityCreateRequest request,
@@ -35,19 +35,19 @@ public class ActivityController {
         return Result.success(activityService.createActivity(request, adminId));
     }
 
-    @ApiOperation("游玩项目列表")
+    @ApiOperation(value = "游玩项目列表", notes = "分页查询游玩项目列表，支持按名称、状态、分类等条件筛选。返回摘要信息，按sortOrder倒序+创建时间倒序排列。\n\n**关联字典**：\n- activity_category：活动分类（筛选+列表显示）\n- activity_billing_type：计费方式（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<ActivityListVO>> listActivities(@ApiParam("游玩项目查询请求") @Valid ActivityQueryRequest query) {
         return Result.success(activityService.listActivities(query));
     }
 
-    @ApiOperation("游玩项目详情")
+    @ApiOperation(value = "游玩项目详情", notes = "获取游玩项目完整信息，包含富文本内容、素材URL、标签、价格日历等。\n\n**关联字典**：\n- activity_category：活动分类（详情显示）\n- activity_billing_type：计费方式（详情显示）")
     @GetMapping("/item/{activityId}")
     public Result<ActivityVO> getActivity(@ApiParam("游玩项目ID") @PathVariable Long activityId) {
         return Result.success(activityService.getActivity(activityId));
     }
 
-    @ApiOperation("更新游玩项目")
+    @ApiOperation(value = "更新游玩项目", notes = "更新游玩项目基本信息，不改变当前状态。已上架的项目修改后仍保持上架。\n\n**关联字典**：\n- activity_category：活动分类（表单选择）\n- activity_billing_type：计费方式（表单选择）")
     @PutMapping("/item/{activityId}")
     public Result<ActivityVO> updateActivity(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -57,7 +57,7 @@ public class ActivityController {
         return Result.success(activityService.updateActivity(activityId, request, adminId));
     }
 
-    @ApiOperation("删除游玩项目")
+    @ApiOperation(value = "删除游玩项目", notes = "软删除游玩项目。仅SUPER_ADMIN或创建者可操作。删除后关联的素材引用会被清理。")
     @DeleteMapping("/item/{activityId}")
     public Result<Void> deleteActivity(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -68,7 +68,7 @@ public class ActivityController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。审批通过后自动更新状态，返回审批单号spNo。")
     @PostMapping("/item/{activityId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -80,7 +80,7 @@ public class ActivityController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("启用/禁用切换")
+    @ApiOperation(value = "启用/禁用切换", notes = "直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/item/{activityId}/status")
     public Result<Void> updateStatus(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -91,7 +91,7 @@ public class ActivityController {
         return Result.success();
     }
 
-    @ApiOperation("批量启用/禁用")
+    @ApiOperation(value = "批量启用/禁用", notes = "批量修改多个游玩项目的状态，跳过审批流程。")
     @PutMapping("/items/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("游玩项目状态请求") @Valid @RequestBody ActivityStatusRequest request,
@@ -103,7 +103,7 @@ public class ActivityController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个游玩项目。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/items/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java
index 9fec542..3fff48f 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java
@@ -25,7 +25,7 @@ public class ActivityPriceCalendarController {
 
     private final ActivityPriceCalendarService priceService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询游玩项目的每日价格和可接待状态。")
     @GetMapping("/item/{activityId}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -34,7 +34,7 @@ public class ActivityPriceCalendarController {
         return Result.success(priceService.getPriceCalendar(activityId, year, month));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格", notes = "在指定日期范围内批量设置成本价和可接待状态。支持按星期过滤和排除特定日期。")
     @PutMapping("/item/{activityId}/prices")
     public Result<Void> batchSetPrices(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -43,7 +43,7 @@ public class ActivityPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改可接待状态")
+    @ApiOperation(value = "批量修改可接待状态", notes = "批量修改指定日期范围内的可接待状态，不影响价格。")
     @PutMapping("/item/{activityId}/prices/batch-status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -52,7 +52,7 @@ public class ActivityPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量清除价格")
+    @ApiOperation(value = "批量清除价格", notes = "删除指定日期范围内的所有价格记录。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/item/{activityId}/prices")
     public Result<Void> deletePrices(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,

`hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java
index 2a01cd2..80b72a0 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java
@@ -27,7 +27,7 @@ public class ActivityTagController {
 
     private final ActivityTagService tagService;
 
-    @ApiOperation("获取管理标签列表（分页）")
+    @ApiOperation(value = "获取管理标签列表（分页）", notes = "分页查询游玩项目标签库，支持按关键词搜索。包含预设标签和自定义标签。")
     @GetMapping("/tags")
     public Result<PageResult<ActivityTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class ActivityTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("获取全部标签")
+    @ApiOperation(value = "获取全部标签", notes = "不分页返回所有标签，用于项目编辑时的标签选择下拉。")
     @GetMapping("/tags/all")
     public Result<List<ActivityTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建管理标签")
+    @ApiOperation(value = "创建管理标签", notes = "创建预设标签，标签名不可重复。可指定颜色(tagColor)，默认#409EFF。")
     @PostMapping("/tag")
     public Result<ActivityTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class ActivityTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "按名称查找或自动创建标签。用于项目编辑时快速输入新标签。")
     @PostMapping("/tag/adhoc")
     public Result<ActivityTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class ActivityTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("编辑标签")
+    @ApiOperation(value = "编辑标签", notes = "修改标签名称或颜色，所有关联项目自动生效。")
     @PutMapping("/tag/{tagId}")
     public Result<ActivityTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class ActivityTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并自动解除所有项目与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("更新项目标签")
+    @ApiOperation(value = "更新项目标签", notes = "全量替换指定项目的标签列表。传入tagIds为最终关联的标签ID列表，为空则清除所有标签。")
     @PutMapping("/item/{activityId}/tags")
     public Result<Void> updateActivityTags(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -87,7 +87,7 @@ public class ActivityTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量打标签")
+    @ApiOperation(value = "批量打标签", notes = "对多个项目批量添加/移除标签。增量操作，不影响未指定的标签。")
     @PutMapping("/items/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {

`hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java
index e24ce98..1b5dd8f 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java
@@ -17,7 +17,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】游玩项目（Feign调用）")
+@Api(tags = "【内部接口】游玩项目（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/activity")
 @RequiredArgsConstructor
@@ -25,7 +25,7 @@ public class InternalActivityController {
 
     private final ActivityService activityService;
 
-    @ApiOperation("获取项目简要信息")
+    @ApiOperation(value = "获取项目简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个游玩项目的简要信息，返回ID、名称、分类编码、计费类型、状态。不存在时返回错误。\n\n**关联字典**：\n- activity_category（活动分类，返回字段categoryCode）：OUTDOOR=户外, INDOOR=室内, CULTURAL=文化, ADVENTURE=探险\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/item/{activityId}")
     public Result<Map<String, Object>> getActivityBrief(@PathVariable Long activityId) {
         Activity item = activityService.getActivityEntity(activityId);
@@ -41,7 +41,7 @@ public class InternalActivityController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取项目简要信息")
+    @ApiOperation(value = "批量获取项目简要信息", notes = "【仅限内部Feign调用】批量获取游玩项目简要信息，最多500个ID。不存在的ID自动过滤，返回实际找到的项目列表。供产品服务批量查询行程节点绑定的活动资源。\n\n**关联字典**：\n- activity_category（活动分类，返回字段categoryCode）：OUTDOOR=户外, INDOOR=室内, CULTURAL=文化, ADVENTURE=探险\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/items/batch")
     public Result<List<Map<String, Object>>> getActivityBatch(@RequestParam @Size(max = 500) List<Long> activityIds) {
         List<Map<String, Object>> results = activityIds.stream()
@@ -61,9 +61,9 @@ public class InternalActivityController {
         return Result.success(results);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo(审批单号)匹配游玩项目并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         activityService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java
index 63164c0..03e9f1d 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java
@@ -14,7 +14,7 @@ import org.springframework.web.bind.annotation.*;
 /**
  * C端活动内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  */
-@Api(tags = "【内部接口】小程序活动（Feign调用）")
+@Api(tags = "【内部接口】小程序活动（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/activity")
 @RequiredArgsConstructor
@@ -22,14 +22,14 @@ public class InternalMpActivityController {
 
     private final ActivityService activityService;
 
-    @ApiOperation("C端活动列表")
+    @ApiOperation(value = "C端活动列表", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用。强制status=1只返回已上架活动，支持分页和筛选。C端用户通过小程序间接访问。\n\n**关联字典**：\n- activity_category（活动分类，返回字段categoryCode）：OUTDOOR=户外, INDOOR=室内, CULTURAL=文化, ADVENTURE=探险\n- environment_type（环境类型，返回字段environmentType）：INDOOR=室内, OUTDOOR=户外, MIXED=混合")
     @GetMapping("/list")
     public Result<PageResult<ActivityListVO>> listActivities(ActivityQueryRequest query) {
         query.setStatus(1);
         return Result.success(activityService.listActivities(query));
     }
 
-    @ApiOperation("C端活动详情")
+    @ApiOperation(value = "C端活动详情", notes = "【仅限内部Feign调用】供mp-service获取活动完整详情，包含封面、轮播图、标签、富文本介绍等。注意：不限制status，由BFF层校验是否展示。\n\n**关联字典**：\n- activity_category（活动分类，返回字段categoryCode）：OUTDOOR=户外, INDOOR=室内, CULTURAL=文化, ADVENTURE=探险\n- environment_type（环境类型，返回字段environmentType）：INDOOR=室内, OUTDOOR=户外, MIXED=混合")
     @GetMapping("/{activityId}")
     public Result<ActivityVO> getActivityDetail(@PathVariable Long activityId) {
         ActivityVO vo = activityService.getActivity(activityId);

`hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java
index 3fcaf95..a7c45f5 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java
@@ -40,7 +40,7 @@ import java.util.stream.Collectors;
  */
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】资源摘要（Feign调用）")
+@Api(tags = "【内部接口】资源摘要（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/resource")
 @RequiredArgsConstructor
@@ -60,7 +60,7 @@ public class InternalMpResourceBriefController {
 
     private final MaterialRefFeignClient materialRefClient;
 
-    @ApiOperation("批量查询景区摘要")
+    @ApiOperation(value = "批量查询景区摘要", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用（收藏列表/足迹列表），返回最小化信息：id、name、coverUrl、tags。最多500个ID。")
     @GetMapping("/scenic/brief")
     public Result<List<Map<String, Object>>> getScenicBrief(@RequestParam @Size(max = 500) List<Long> ids) {
         if (ids == null || ids.isEmpty()) {
@@ -94,7 +94,7 @@ public class InternalMpResourceBriefController {
         return Result.success(result);
     }
 
-    @ApiOperation("批量查询餐厅摘要")
+    @ApiOperation(value = "批量查询餐厅摘要", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用，返回最小化信息。最多500个ID。")
     @GetMapping("/restaurant/brief")
     public Result<List<Map<String, Object>>> getRestaurantBrief(@RequestParam @Size(max = 500) List<Long> ids) {
         if (ids == null || ids.isEmpty()) {
@@ -126,7 +126,7 @@ public class InternalMpResourceBriefController {
         return Result.success(result);
     }
 
-    @ApiOperation("批量查询活动摘要")
+    @ApiOperation(value = "批量查询活动摘要", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用，返回最小化信息。最多500个ID。")
     @GetMapping("/activity/brief")
     public Result<List<Map<String, Object>>> getActivityBrief(@RequestParam @Size(max = 500) List<Long> ids) {
         if (ids == null || ids.isEmpty()) {

`hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java
index d4158a8..44cd22e 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java
@@ -25,7 +25,7 @@ import org.springframework.web.bind.annotation.*;
  * </p>
  */
 @Slf4j
-@Api(tags = "【内部接口】资源审批（Feign调用）")
+@Api(tags = "【内部接口】资源审批（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/resource")
 @RequiredArgsConstructor
@@ -42,9 +42,9 @@ public class InternalResourceController {
     private final StaffService staffService;
 
     /** 处理审批回调 - 分发到9个资源领域服务 */
-    @ApiOperation("处理审批回调 - 分发到9个资源领域服务")
+    @ApiOperation(value = "处理审批回调 - 分发到9个资源领域服务", notes = "【仅限内部Feign调用】接收企微审批回调结果，按thirdNo(审批单号)在9个资源领域中匹配并更新状态。每个领域服务内部通过approval_no匹配，未找到则忽略（幂等处理）。由hl-callback-service通过MQ消费后调用。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
 
         // 分发到9个领域服务 - 每个服务内部检查approval_no

`hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java
index a6adb66..e726a14 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java
@@ -41,7 +41,7 @@ import java.util.stream.Collectors;
  * 供产品服务的行程节点获取绑定资源的详细信息（含图片、地址等）
  */
 @Slf4j
-@Api(tags = "【内部接口】资源详情（Feign调用）")
+@Api(tags = "【内部接口】资源详情（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/resource")
 @RequiredArgsConstructor
@@ -69,7 +69,7 @@ public class InternalResourceDetailController {
      * @param activityIds   活动ID列表
      * @return resourceType:resourceId → ResourceDetailDTO
      */
-    @ApiOperation("批量查询资源详情（行程节点用）")
+    @ApiOperation(value = "批量查询资源详情（行程节点用）", notes = "【仅限内部Feign调用】供产品服务获取行程节点绑定资源的详细信息。按类型分组查询，返回Map<resourceType:resourceId, ResourceDetailDTO>。包含封面、轮播图URL、地址、坐标、标签、富文本介绍等完整信息。\n\n**关联字典**：\n- city（城市，返回字段city）")
     @GetMapping("/batch-details")
     public Result<Map<String, ResourceDetailDTO>> batchDetails(
             @RequestParam(required = false) List<Long> scenicIds,

`hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java
index 366168b..e1ddd03 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java
@@ -53,7 +53,7 @@ import java.util.stream.Collectors;
 @RestController
 @RequestMapping("/internal/resource/prices")
 @RequiredArgsConstructor
-@Api(tags = "【内部接口】资源价格（Feign调用）")
+@Api(tags = "【内部接口】资源价格（Feign调用）", hidden = true)
 public class InternalResourcePriceController {
 
     private final ScenicPriceCalendarMapper scenicPriceMapper;
@@ -71,7 +71,7 @@ public class InternalResourcePriceController {
     private final SuppliesItemMapper suppliesItemMapper;
     private final SuppliesService suppliesService;
 
-    /** 查询景区价格 */
+    /** 查询景区价格 - 按景区ID和日期范围查询价格日历的成本价 */
     @PostMapping("/scenic")
     public Result<List<PriceVO>> getScenicPrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -108,7 +108,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询酒店价格（按hotelId查最低房型价格） */
+    /** 查询酒店价格 - 按hotelId查询日期范围内最低房型的成本价（取所有房型中最低价） */
     @PostMapping("/hotel")
     public Result<List<PriceVO>> getHotelPrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -143,7 +143,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询房型价格（按roomTypeId精确查询） */
+    /** 查询房型价格 - 按roomTypeId精确查询日期范围内的成本价（取最低价） */
     @PostMapping("/room-type")
     public Result<List<PriceVO>> getRoomTypePrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -178,7 +178,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询活动价格 */
+    /** 查询活动价格 - 按活动ID和日期范围查询价格日历的成本价 */
     @PostMapping("/activity")
     public Result<List<PriceVO>> getActivityPrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -214,7 +214,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询车辆价格 */
+    /** 查询车辆价格 - 按车型ID和日期范围查询价格日历的成本价 */
     @PostMapping("/vehicle")
     public Result<List<PriceVO>> getVehiclePrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -250,7 +250,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询服务项价格 */
+    /** 查询服务项价格 - 按服务项ID和日期范围查询价格日历的成本价 */
     @PostMapping("/service")
     public Result<List<PriceVO>> getServicePrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -283,13 +283,13 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询餐厅价格（餐厅无价格日历，返回空） */
+    /** 查询餐厅价格 - 餐厅无独立价格日历，始终返回空列表（餐费通过费用项管理） */
     @PostMapping("/restaurant")
     public Result<List<PriceVO>> getRestaurantPrices(@RequestBody PriceQuery query) {
         return Result.success(new ArrayList<>());
     }
 
-    /** 查询服务人员价格（按人员类型） */
+    /** 查询服务人员价格 - 按staffType(人员类型)和日期范围查询价格日历的成本价（人员价格按类型而非个人） */
     @PostMapping("/staff")
     public Result<List<PriceVO>> getStaffPrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -321,7 +321,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询酒店下所有房型（简要信息） */
+    /** 查询酒店下所有已启用房型 - 返回roomTypeId、name、maxOccupancy、basePrice，按sortOrder排序 */
     @GetMapping("/room-types-by-hotel/{hotelId}")
     public Result<List<RoomTypeSimpleVO>> getRoomTypesByHotel(@PathVariable Long hotelId) {
         List<RoomType> roomTypes = roomTypeMapper.selectList(
@@ -336,7 +336,7 @@ public class InternalResourcePriceController {
         return Result.success(vos);
     }
 
-    /** 查询所有可用车型（简要信息） */
+    /** 查询所有已启用车型 - 返回vehicleId、name、seatCount、basePrice，按sortOrder排序，供产品服务车辆下拉选择使用 */
     @GetMapping("/vehicle-models")
     public Result<List<VehicleSimpleVO>> getVehicleModels() {
         List<VehicleModel> vehicles = vehicleModelMapper.selectList(

`hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java
index 019a26f..3ef23db 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java
@@ -14,7 +14,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.HashMap;
 import java.util.Map;
 
-@Api(tags = "【内部接口】资源统计（Feign调用）")
+@Api(tags = "【内部接口】资源统计（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/resource")
 @RequiredArgsConstructor
@@ -24,7 +24,7 @@ public class InternalResourceStatsController {
     private final RoomTypeMapper roomTypeMapper;
     private final VehicleModelMapper vehicleModelMapper;
 
-    @ApiOperation("获取酒店统计")
+    @ApiOperation(value = "获取酒店统计", notes = "【仅限内部Feign调用】返回酒店总数和房型总数，供管理后台仪表盘展示。")
     @GetMapping("/hotel/stats")
     public Result<Map<String, Object>> getHotelStats() {
         long totalHotels = hotelMapper.selectCount(null);
@@ -36,7 +36,7 @@ public class InternalResourceStatsController {
         return Result.success(stats);
     }
 
-    @ApiOperation("获取车辆统计")
+    @ApiOperation(value = "获取车辆统计", notes = "【仅限内部Feign调用】返回车型总数，供管理后台仪表盘展示。")
     @GetMapping("/vehicle/stats")
     public Result<Map<String, Object>> getVehicleStats() {
         long totalVehicles = vehicleModelMapper.selectCount(null);

`hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java
index ce21f8c..b138078 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java
@@ -28,7 +28,7 @@ public class CostItemController {
 
     private final CostItemService costItemService;
 
-    @ApiOperation("创建费用项")
+    @ApiOperation(value = "创建费用项", notes = "新建费用项（如门票成本、餐费、保险费等），用于产品报价计算。费用项有独立的价格日历，价格变更会记录变更日志。创建后需走企微审批上架。\n\n**关联字典**：\n- cost_category：费用分类（表单选择）\n- cost_apply_role：适用角色（表单选择）\n- cost_unit：计量单位（表单选择）")
     @PostMapping("/item")
     public Result<CostItemVO> createCostItem(@ApiParam("费用项创建请求") @Valid @RequestBody CostItemCreateRequest request,
                                               HttpServletRequest httpRequest) {
@@ -36,19 +36,19 @@ public class CostItemController {
         return Result.success(costItemService.createCostItem(request, adminId));
     }
 
-    @ApiOperation("费用项列表")
+    @ApiOperation(value = "费用项列表", notes = "分页查询费用项列表，支持按名称、状态等条件筛选。\n\n**关联字典**：\n- cost_category：费用分类（筛选+列表显示）\n- cost_apply_role：适用角色（筛选+列表显示）\n- cost_unit：计量单位（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<CostItemListVO>> listCostItems(@ApiParam("费用项查询请求") @Valid CostItemQueryRequest query) {
         return Result.success(costItemService.listCostItems(query));
     }
 
-    @ApiOperation("费用项详情")
+    @ApiOperation(value = "费用项详情", notes = "获取费用项完整信息，包含当前价格、引用计数等。\n\n**关联字典**：\n- cost_category：费用分类（详情显示）\n- cost_apply_role：适用角色（详情显示）\n- cost_unit：计量单位（详情显示）")
     @GetMapping("/item/{costId}")
     public Result<CostItemVO> getCostItem(@ApiParam("费用项ID") @PathVariable Long costId) {
         return Result.success(costItemService.getCostItem(costId));
     }
 
-    @ApiOperation("更新费用项")
+    @ApiOperation(value = "更新费用项", notes = "更新费用项信息。如果修改了价格，会自动记录价格变更日志。\n\n**关联字典**：\n- cost_category：费用分类（表单选择）\n- cost_apply_role：适用角色（表单选择）\n- cost_unit：计量单位（表单选择）")
     @PutMapping("/item/{costId}")
     public Result<CostItemVO> updateCostItem(@ApiParam("费用项ID") @PathVariable Long costId,
                                               @ApiParam("费用项更新请求") @Valid @RequestBody CostItemUpdateRequest request,
@@ -57,7 +57,7 @@ public class CostItemController {
         return Result.success(costItemService.updateCostItem(costId, request, adminId));
     }
 
-    @ApiOperation("删除费用项")
+    @ApiOperation(value = "删除费用项", notes = "软删除费用项。仅SUPER_ADMIN或创建者可操作。被产品引用(refCount>0)的费用项不建议删除。")
     @DeleteMapping("/item/{costId}")
     public Result<Void> deleteCostItem(@ApiParam("费用项ID") @PathVariable Long costId, HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);
@@ -66,7 +66,7 @@ public class CostItemController {
         return Result.success();
     }
 
-    @ApiOperation("提交审批")
+    @ApiOperation(value = "提交审批", notes = "向企微OA提交费用项启用/禁用审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。")
     @PostMapping("/item/{costId}/submit-approval")
     public Result<java.util.Map<String, String>> submitApproval(@ApiParam("费用项ID") @PathVariable Long costId,
                                                                 @ApiParam("审批提交请求体") @Valid @RequestBody ApprovalSubmitRequest request,
@@ -76,13 +76,13 @@ public class CostItemController {
         return Result.success(java.util.Map.of("spNo", spNo));
     }
 
-    @ApiOperation("启用的费用项列表")
+    @ApiOperation(value = "启用的费用项列表", notes = "查询所有已启用(status=1)的费用项，不分页。用于产品编排时选择费用项的下拉列表。\n\n**关联字典**：\n- cost_category：费用分类（列表显示）\n- cost_apply_role：适用角色（列表显示）\n- cost_unit：计量单位（列表显示）")
     @GetMapping("/items/enabled")
     public Result<List<CostItemVO>> listEnabledCostItems() {
         return Result.success(costItemService.listEnabledCostItems());
     }
 
-    @ApiOperation("费用项价格变更记录")
+    @ApiOperation(value = "费用项价格变更记录", notes = "查询费用项的历史价格变更记录，按时间倒序排列。用于追溯价格调整历史。")
     @GetMapping("/item/{costId}/price-logs")
     public Result<List<CostPriceLogVO>> getPriceLogs(@ApiParam("费用项ID") @PathVariable Long costId) {
         return Result.success(costItemService.getPriceLogs(costId));

`hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java
index 862c1b2..95007f0 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java
@@ -26,7 +26,7 @@ public class CostPriceCalendarController {
 
     private final CostPriceCalendarService priceCalendarService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询费用项的每日价格。费用项价格日历用于产品报价计算时按日期获取成本价。")
     @GetMapping("/item/{costId}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(@ApiParam("费用项ID") @PathVariable Long costId,
                                                      @ApiParam("年份") @RequestParam @Min(2020) @Max(2100) Integer year,
@@ -34,7 +34,7 @@ public class CostPriceCalendarController {
         return Result.success(priceCalendarService.getPriceCalendar(costId, year, month));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格", notes = "在指定日期范围内批量设置费用项的成本价。")
     @PutMapping("/item/{costId}/prices")
     public Result<Void> batchSetPrices(@ApiParam("费用项ID") @PathVariable Long costId,
                                         @ApiParam("价格日历设置请求") @Valid @RequestBody PriceCalendarSetRequest request) {
@@ -42,7 +42,7 @@ public class CostPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("清除价格日历")
+    @ApiOperation(value = "清除价格日历", notes = "删除指定日期范围内费用项的价格记录。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/item/{costId}/prices")
     public Result<Void> deletePrices(@ApiParam("费用项ID") @PathVariable Long costId,
                                       @ApiParam("开始日期") @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate startDate,

`hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java
index 5e27f64..361c8de 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java
@@ -20,7 +20,7 @@ import java.util.Map;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】费用项（Feign调用）")
+@Api(tags = "【内部接口】费用项（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/cost")
 @RequiredArgsConstructor
@@ -28,21 +28,21 @@ public class InternalCostController {
 
     private final CostItemService costItemService;
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配费用项并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         costItemService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();
     }
 
-    @ApiOperation("批量获取费用项")
+    @ApiOperation(value = "批量获取费用项", notes = "【仅限内部Feign调用】批量获取费用项完整信息（含名称、分类、计费类型、基础价格等），最多500个ID。供产品服务批量查询产品关联的费用项。\n\n**关联字典**：\n- cost_unit（计费单位，返回字段unit）：PER_PERSON=元/人, PER_VEHICLE=元/台, PER_DAY=元/天, PER_TIME=元/次, PER_ROOM=元/间, PER_TABLE=元/桌, FIXED=固定金额\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/items/batch")
     public Result<List<CostItemVO>> batchGetCostItems(@RequestParam @Size(max = 500) List<Long> costIds) {
         return Result.success(costItemService.batchGetCostItems(costIds));
     }
 
-    @ApiOperation("按日期获取费用项价格")
+    @ApiOperation(value = "按日期获取费用项价格", notes = "【仅限内部Feign调用】按指定日期批量查询费用项的成本价格。返回Map<costId字符串, 价格>。优先取价格日历，无日历则取basePrice。供产品服务报价计算器使用。")
     @GetMapping("/items/prices-by-date")
     public Result<Map<String, BigDecimal>> getByDatePrices(
             @RequestParam @Size(max = 500) List<Long> costIds,
@@ -50,7 +50,7 @@ public class InternalCostController {
         return Result.success(costItemService.getByDatePrices(costIds, date));
     }
 
-    @ApiOperation("更新引用计数")
+    @ApiOperation(value = "更新引用计数", notes = "【仅限内部Feign调用】更新费用项的引用计数。delta>0表示新增引用，delta<0表示减少引用。供产品服务在关联/取消关联费用项时调用，用于统计资源被使用次数。")
     @PostMapping("/item/{costId}/ref-count")
     public Result<Void> updateRefCount(@PathVariable Long costId, @RequestParam int delta) {
         costItemService.updateRefCount(costId, delta);

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java
index 4a0c2c5..7faaef1 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java
@@ -26,7 +26,7 @@ public class HotelController {
 
     private final HotelService hotelService;
 
-    @ApiOperation("创建住宿")
+    @ApiOperation(value = "创建住宿", notes = "新建住宿资源（酒店/民宿/营地等），初始状态为草稿(status=0)。创建后需通过「提交启用/禁用审批」走企微OA审批流程才能上架。住宿下可继续创建房型（RoomType），房型有独立的价格日历。\n\n**关联字典**：\n- hotel_type：住宿类型（表单选择）\n- hotel_star_level：酒店星级（表单选择）\n- hotel_facility：酒店设施（表单多选）")
     @PostMapping("/item")
     public Result<HotelVO> createHotel(
             @ApiParam("住宿创建请求") @Valid @RequestBody HotelCreateRequest request,
@@ -35,25 +35,25 @@ public class HotelController {
         return Result.success(hotelService.createHotel(request, adminId));
     }
 
-    @ApiOperation("住宿列表")
+    @ApiOperation(value = "住宿列表", notes = "分页查询住宿列表，支持按名称关键词、状态、住宿类型等条件筛选。返回列表摘要信息，按sortOrder倒序+创建时间倒序排列。\n\n**关联字典**：\n- hotel_type：住宿类型（筛选+列表显示）\n- hotel_star_level：酒店星级（筛选+列表显示）\n- hotel_facility：酒店设施（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<HotelListVO>> listHotels(@ApiParam("住宿查询请求") @Valid HotelQueryRequest query) {
         return Result.success(hotelService.listHotels(query));
     }
 
-    @ApiOperation("所有启用的住宿（不分页，仅ID和名称）")
+    @ApiOperation(value = "所有启用的住宿（不分页，仅ID和名称）", notes = "返回所有已上架(status=1)的住宿简要信息，用于下拉选择框。每项只含hotelId和name字段。适用于房型管理时选择所属住宿、产品编排时绑定住宿资源等场景。")
     @GetMapping("/items/all-simple")
     public Result<List<Map<String, Object>>> listAllSimple() {
         return Result.success(hotelService.listAllSimple());
     }
 
-    @ApiOperation("住宿详情")
+    @ApiOperation(value = "住宿详情", notes = "获取住宿完整信息，包含素材URL、标签列表、房型列表等。素材ID会自动解析为OSS访问地址。\n\n**关联字典**：\n- hotel_type：住宿类型（详情显示）\n- hotel_star_level：酒店星级（详情显示）\n- hotel_facility：酒店设施（详情显示）")
     @GetMapping("/item/{hotelId}")
     public Result<HotelVO> getHotel(@ApiParam("住宿ID") @PathVariable Long hotelId) {
         return Result.success(hotelService.getHotel(hotelId));
     }
 
-    @ApiOperation("更新住宿")
+    @ApiOperation(value = "更新住宿", notes = "更新住宿基本信息。更新不会改变当前状态，已上架的住宿修改后仍保持上架状态。\n\n**关联字典**：\n- hotel_type：住宿类型（表单选择）\n- hotel_star_level：酒店星级（表单选择）\n- hotel_facility：酒店设施（表单多选）")
     @PutMapping("/item/{hotelId}")
     public Result<HotelVO> updateHotel(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -63,7 +63,7 @@ public class HotelController {
         return Result.success(hotelService.updateHotel(hotelId, request, adminId));
     }
 
-    @ApiOperation("删除住宿")
+    @ApiOperation(value = "删除住宿", notes = "软删除住宿。仅SUPER_ADMIN或创建者可操作。删除住宿会同时删除其下所有房型和价格日历数据。")
     @DeleteMapping("/item/{hotelId}")
     public Result<Void> deleteHotel(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -74,7 +74,7 @@ public class HotelController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交住宿启用/禁用审批。targetStatus=1申请上架，targetStatus=2申请下架。审批通过后自动更新状态。返回企微审批单号spNo。")
     @PostMapping("/item/{hotelId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -86,7 +86,7 @@ public class HotelController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("启用/禁用切换")
+    @ApiOperation(value = "启用/禁用切换", notes = "直接修改住宿状态（跳过审批），仅限SUPER_ADMIN使用。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/item/{hotelId}/status")
     public Result<Void> updateStatus(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -97,7 +97,7 @@ public class HotelController {
         return Result.success();
     }
 
-    @ApiOperation("批量启用/禁用")
+    @ApiOperation(value = "批量启用/禁用", notes = "批量修改多个住宿的状态，跳过审批流程。hotelIds为住宿ID列表（字符串格式）。")
     @PutMapping("/items/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("住宿状态请求") @Valid @RequestBody HotelStatusRequest request,
@@ -109,7 +109,7 @@ public class HotelController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个住宿及其关联的房型和价格日历。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/items/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java
index 3b229f8..02e8708 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java
@@ -27,7 +27,7 @@ public class HotelTagController {
 
     private final HotelTagService tagService;
 
-    @ApiOperation("预设标签列表（分页）")
+    @ApiOperation(value = "预设标签列表（分页）", notes = "分页查询住宿标签库，支持按关键词搜索。")
     @GetMapping("/tags")
     public Result<PageResult<HotelTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class HotelTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("所有标签列表")
+    @ApiOperation(value = "所有标签列表", notes = "不分页返回所有标签，用于住宿编辑时的标签选择。")
     @GetMapping("/tags/all")
     public Result<List<HotelTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建标签")
+    @ApiOperation(value = "创建标签", notes = "创建预设标签，标签名不可重复。")
     @PostMapping("/tag")
     public Result<HotelTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class HotelTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("查找或创建自定义标签")
+    @ApiOperation(value = "查找或创建自定义标签", notes = "按名称查找标签，不存在则自动创建。用于住宿编辑时快速输入新标签。")
     @PostMapping("/tag/adhoc")
     public Result<HotelTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class HotelTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("更新标签")
+    @ApiOperation(value = "更新标签", notes = "修改标签名称或颜色，所有关联住宿自动生效。")
     @PutMapping("/tag/{tagId}")
     public Result<HotelTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class HotelTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并解除所有住宿与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("设置住宿标签")
+    @ApiOperation(value = "设置住宿标签", notes = "全量替换指定住宿的标签列表。")
     @PutMapping("/item/{hotelId}/tags")
     public Result<Void> updateHotelTags(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -87,7 +87,7 @@ public class HotelTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量添加/移除标签")
+    @ApiOperation(value = "批量添加/移除标签", notes = "对多个住宿批量添加/移除标签。增量操作，不影响未指定的标签。")
     @PutMapping("/items/batch/tags")
     public Result<Void> batchUpdateTags(@ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {
         List<Long> hotelIds = request.getHotelIds().stream()

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java
index c758f6e..4b81939 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java
@@ -18,7 +18,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】住宿（Feign调用）")
+@Api(tags = "【内部接口】住宿（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/hotel")
 @RequiredArgsConstructor
@@ -27,7 +27,7 @@ public class InternalHotelController {
     private final HotelService hotelService;
     private final RoomTypeService roomTypeService;
 
-    @ApiOperation("获取住宿简要信息")
+    @ApiOperation(value = "获取住宿简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个住宿的简要信息，返回ID、名称、住宿类型、状态。不存在时返回错误。\n\n**关联字典**：\n- hotel_type（住宿类型，返回字段hotelType）：HOTEL=酒店, GUESTHOUSE=民宿, RESORT=度假村, CAMP=营地, HOMESTAY=农家院\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/item/{hotelId}")
     public Result<Map<String, Object>> getHotelBrief(@PathVariable Long hotelId) {
         Hotel item = hotelService.getHotelEntity(hotelId);
@@ -42,7 +42,7 @@ public class InternalHotelController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取住宿简要信息")
+    @ApiOperation(value = "批量获取住宿简要信息", notes = "【仅限内部Feign调用】批量获取住宿简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询行程节点绑定的住宿资源。\n\n**关联字典**：\n- hotel_type（住宿类型，返回字段hotelType）：HOTEL=酒店, GUESTHOUSE=民宿, RESORT=度假村, CAMP=营地, HOMESTAY=农家院\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/items/batch")
     public Result<List<Map<String, Object>>> getHotelBatch(@RequestParam @Size(max = 500) List<Long> hotelIds) {
         List<Map<String, Object>> results = hotelIds.stream()
@@ -61,9 +61,9 @@ public class InternalHotelController {
         return Result.success(results);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配住宿和房型并更新启用/禁用状态。住宿和房型共享同一审批模板，此接口同时尝试匹配两者。由hl-callback-service通过MQ消费后调用。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         hotelService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         // Also try room type (same template, same callback)

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java
index ce4fd47..2a820f5 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java
@@ -14,7 +14,7 @@ import org.springframework.web.bind.annotation.*;
 /**
  * C端住宿内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  */
-@Api(tags = "【内部接口】小程序酒店（Feign调用）")
+@Api(tags = "【内部接口】小程序酒店（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/hotel")
 @RequiredArgsConstructor
@@ -22,7 +22,7 @@ public class InternalMpHotelController {
 
     private final HotelService hotelService;
 
-    @ApiOperation("C端住宿列表")
+    @ApiOperation(value = "C端住宿列表", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用。强制status=1只返回已上架住宿，支持分页和筛选。C端用户通过小程序间接访问。\n\n**关联字典**：\n- hotel_type（住宿类型，返回字段hotelType）：HOTEL=酒店, GUESTHOUSE=民宿, RESORT=度假村, CAMP=营地, HOMESTAY=农家院\n- hotel_star（星级，返回字段starLevel）：FIVE=五星, FOUR=四星, THREE=三星, UNRATED=未评级")
     @GetMapping("/list")
     public Result<PageResult<HotelListVO>> listHotels(HotelQueryRequest query) {
         // Force status=1 for C-side (only show published hotels)
@@ -30,7 +30,7 @@ public class InternalMpHotelController {
         return Result.success(hotelService.listHotels(query));
     }
 
-    @ApiOperation("C端住宿详情")
+    @ApiOperation(value = "C端住宿详情", notes = "【仅限内部Feign调用】供mp-service获取住宿完整详情，包含房型列表、封面、轮播图、地址等。注意：不限制status，由BFF层校验是否展示。\n\n**关联字典**：\n- hotel_type（住宿类型，返回字段hotelType）：HOTEL=酒店, GUESTHOUSE=民宿, RESORT=度假村, CAMP=营地, HOMESTAY=农家院\n- hotel_star（星级，返回字段starLevel）：FIVE=五星, FOUR=四星, THREE=三星, UNRATED=未评级")
     @GetMapping("/{hotelId}")
     public Result<HotelVO> getHotelDetail(@PathVariable Long hotelId) {
         HotelVO vo = hotelService.getHotel(hotelId);

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java
index cf6df6c..d883d85 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java
@@ -25,7 +25,7 @@ public class RoomPriceCalendarController {
 
     private final RoomPriceCalendarService priceCalendarService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询房型的每日价格和可售状态。每个房型有独立的价格日历。")
     @GetMapping("/room-type/{roomTypeId}/prices")
     public Result<RoomPriceCalendarVO> getPriceCalendar(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,
@@ -34,7 +34,7 @@ public class RoomPriceCalendarController {
         return Result.success(priceCalendarService.getPriceCalendar(roomTypeId, year, month));
     }
 
-    @ApiOperation("批量设置价格日历")
+    @ApiOperation(value = "批量设置价格日历", notes = "在指定日期范围内批量设置房型的成本价和可售状态。支持按星期过滤和排除特定日期。")
     @PutMapping("/room-type/{roomTypeId}/prices")
     public Result<Void> batchSetPrices(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,
@@ -43,7 +43,7 @@ public class RoomPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改日期可售状态")
+    @ApiOperation(value = "批量修改日期可售状态", notes = "批量修改指定日期范围内房型的可售状态，不影响价格。")
     @PutMapping("/room-type/{roomTypeId}/prices/batch-status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,
@@ -52,7 +52,7 @@ public class RoomPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("删除价格日历")
+    @ApiOperation(value = "删除价格日历", notes = "删除指定日期范围内房型的所有价格记录。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/room-type/{roomTypeId}/prices")
     public Result<Void> deletePrices(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java
index 2048f4c..0d9cf42 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java
@@ -26,7 +26,7 @@ public class RoomTypeController {
 
     private final RoomTypeService roomTypeService;
 
-    @ApiOperation("创建房型")
+    @ApiOperation(value = "创建房型", notes = "在指定住宿下创建房型（如标准间、大床房、套房等）。每个房型有独立的价格日历、最大入住人数(maxOccupancy)和基础价格(basePrice)。房型初始状态为草稿(status=0)，需独立审批后才能启用。创建后可通过「提交房型启用审批」接口提交企微OA审批。\n\n**关联字典**：\n- room_category：房型分类（表单选择）\n- bed_type：床型（表单选择）\n- window_type：窗户类型（表单选择）\n- bathroom_type：卫浴类型（表单选择）\n- room_facility：房间设施（表单多选）")
     @PostMapping("/{hotelId}/room-type")
     public Result<RoomTypeVO> createRoomType(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -36,19 +36,19 @@ public class RoomTypeController {
         return Result.success(roomTypeService.createRoomType(hotelId, request, adminId));
     }
 
-    @ApiOperation("房型列表")
+    @ApiOperation(value = "房型列表", notes = "获取指定住宿下的所有房型列表（不分页），按sortOrder排序。\n\n**关联字典**：\n- room_category：房型分类（列表/详情显示）\n- bed_type：床型（列表/详情显示）\n- window_type：窗户类型（列表/详情显示）\n- bathroom_type：卫浴类型（列表/详情显示）\n- room_facility：房间设施（列表/详情显示）")
     @GetMapping("/{hotelId}/room-types")
     public Result<List<RoomTypeVO>> listRoomTypes(@ApiParam("住宿ID") @PathVariable Long hotelId) {
         return Result.success(roomTypeService.listRoomTypes(hotelId));
     }
 
-    @ApiOperation("房型详情")
+    @ApiOperation(value = "房型详情", notes = "获取房型完整信息，包含价格、入住人数、素材等。\n\n**关联字典**：\n- room_category：房型分类（列表/详情显示）\n- bed_type：床型（列表/详情显示）\n- window_type：窗户类型（列表/详情显示）\n- bathroom_type：卫浴类型（列表/详情显示）\n- room_facility：房间设施（列表/详情显示）")
     @GetMapping("/room-type/{roomTypeId}")
     public Result<RoomTypeVO> getRoomType(@ApiParam("房型ID") @PathVariable Long roomTypeId) {
         return Result.success(roomTypeService.getRoomType(roomTypeId));
     }
 
-    @ApiOperation("更新房型")
+    @ApiOperation(value = "更新房型", notes = "更新房型基本信息，不改变当前状态。\n\n**关联字典**：\n- room_category：房型分类（表单选择）\n- bed_type：床型（表单选择）\n- window_type：窗户类型（表单选择）\n- bathroom_type：卫浴类型（表单选择）\n- room_facility：房间设施（表单多选）")
     @PutMapping("/room-type/{roomTypeId}")
     public Result<RoomTypeVO> updateRoomType(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,
@@ -58,14 +58,14 @@ public class RoomTypeController {
         return Result.success(roomTypeService.updateRoomType(roomTypeId, request, adminId));
     }
 
-    @ApiOperation("删除房型")
+    @ApiOperation(value = "删除房型", notes = "软删除房型及其价格日历数据。")
     @DeleteMapping("/room-type/{roomTypeId}")
     public Result<Void> deleteRoomType(@ApiParam("房型ID") @PathVariable Long roomTypeId) {
         roomTypeService.deleteRoomType(roomTypeId);
         return Result.success();
     }
 
-    @ApiOperation("启用/禁用房型")
+    @ApiOperation(value = "启用/禁用房型", notes = "直接修改房型状态（跳过审批）。status=0禁用，status=1启用。禁用后该房型不会出现在C端展示中。")
     @PutMapping("/room-type/{roomTypeId}/status")
     public Result<Void> updateRoomTypeStatus(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,
@@ -74,7 +74,7 @@ public class RoomTypeController {
         return Result.success();
     }
 
-    @ApiOperation("提交房型启用/禁用审批")
+    @ApiOperation(value = "提交房型启用/禁用审批", notes = "向企微OA提交房型启用/禁用审批。审批流程与住宿共享同一模板。返回审批单号spNo。")
     @PostMapping("/room-type/{roomTypeId}/submit-approval")
     public Result<Map<String, String>> submitRoomTypeApproval(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java
index 41d485f..df17f5c 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java
@@ -14,7 +14,7 @@ import org.springframework.web.bind.annotation.*;
 /**
  * C端餐厅内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  */
-@Api(tags = "【内部接口】小程序餐厅（Feign调用）")
+@Api(tags = "【内部接口】小程序餐厅（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/restaurant")
 @RequiredArgsConstructor
@@ -22,7 +22,7 @@ public class InternalMpRestaurantController {
 
     private final RestaurantService restaurantService;
 
-    @ApiOperation("C端餐厅列表")
+    @ApiOperation(value = "C端餐厅列表", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用。强制status=1只返回已上架餐厅，支持分页和筛选。C端用户通过小程序间接访问。\n\n**关联字典**：\n- restaurant_category（餐厅分类，返回字段categoryCode）：CHINESE=中餐, WESTERN=西餐, BBQ=烧烤, HOTPOT=火锅, LOCAL=当地特色")
     @GetMapping("/list")
     public Result<PageResult<RestaurantListVO>> listRestaurants(RestaurantQueryRequest query) {
         // Force status=1 for C-side (only show published restaurants)
@@ -30,7 +30,7 @@ public class InternalMpRestaurantController {
         return Result.success(restaurantService.listRestaurants(query));
     }
 
-    @ApiOperation("C端餐厅详情")
+    @ApiOperation(value = "C端餐厅详情", notes = "【仅限内部Feign调用】供mp-service获取餐厅完整详情，包含封面、轮播图、标签、地址、富文本介绍等。注意：不限制status，由BFF层校验是否展示。\n\n**关联字典**：\n- restaurant_category（餐厅分类，返回字段categoryCode）：CHINESE=中餐, WESTERN=西餐, BBQ=烧烤, HOTPOT=火锅, LOCAL=当地特色")
     @GetMapping("/{restaurantId}")
     public Result<RestaurantVO> getRestaurantDetail(@PathVariable Long restaurantId) {
         RestaurantVO vo = restaurantService.getRestaurant(restaurantId);

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java
index ac8e4db..a87aaea 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java
@@ -17,7 +17,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】餐厅（Feign调用）")
+@Api(tags = "【内部接口】餐厅（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/restaurant")
 @RequiredArgsConstructor
@@ -25,7 +25,7 @@ public class InternalRestaurantController {
 
     private final RestaurantService restaurantService;
 
-    @ApiOperation("\u83b7\u53d6\u9910\u5385\u7b80\u8981\u4fe1\u606f")
+    @ApiOperation(value = "\u83b7\u53d6\u9910\u5385\u7b80\u8981\u4fe1\u606f", notes = "\u3010\u4ec5\u9650\u5185\u90e8Feign\u8c03\u7528\u3011\u4f9b\u4ea7\u54c1\u670d\u52a1\u83b7\u53d6\u5355\u4e2a\u9910\u5385\u7684\u7b80\u8981\u4fe1\u606f\uff0c\u8fd4\u56deID\u3001\u540d\u79f0\u3001\u5206\u7c7b\u7f16\u7801\u3001\u57ce\u5e02\u3001\u72b6\u6001\u3002\u4e0d\u5b58\u5728\u65f6\u8fd4\u56de\u9519\u8bef\u3002\n\n**\u5173\u8054\u5b57\u5178**\uff1a\n- restaurant_category\uff08\u9910\u5385\u5206\u7c7b\uff0c\u8fd4\u56de\u5b57\u6bb5categoryCode\uff09\uff1aCHINESE=\u4e2d\u9910, WESTERN=\u897f\u9910, BBQ=\u70e7\u70e4, HOTPOT=\u706b\u9505, LOCAL=\u5f53\u5730\u7279\u8272\n- common_status\uff08\u72b6\u6001\uff0c\u8fd4\u56de\u5b57\u6bb5status\uff09\uff1aACTIVE=\u542f\u7528, INACTIVE=\u505c\u7528")
     @GetMapping("/item/{restaurantId}")
     public Result<Map<String, Object>> getRestaurantBrief(@PathVariable Long restaurantId) {
         Restaurant restaurant = restaurantService.getRestaurantEntity(restaurantId);
@@ -41,7 +41,7 @@ public class InternalRestaurantController {
         return Result.success(brief);
     }
 
-    @ApiOperation("\u6279\u91cf\u83b7\u53d6\u9910\u5385\u7b80\u8981\u4fe1\u606f")
+    @ApiOperation(value = "\u6279\u91cf\u83b7\u53d6\u9910\u5385\u7b80\u8981\u4fe1\u606f", notes = "\u3010\u4ec5\u9650\u5185\u90e8Feign\u8c03\u7528\u3011\u6279\u91cf\u83b7\u53d6\u9910\u5385\u7b80\u8981\u4fe1\u606f\uff0c\u6700\u591a500\u4e2aID\u3002\u4e0d\u5b58\u5728\u7684ID\u81ea\u52a8\u8fc7\u6ee4\u3002\u4f9b\u4ea7\u54c1\u670d\u52a1\u6279\u91cf\u67e5\u8be2\u884c\u7a0b\u8282\u70b9\u7ed1\u5b9a\u7684\u9910\u5385\u8d44\u6e90\u3002\n\n**\u5173\u8054\u5b57\u5178**\uff1a\n- restaurant_category\uff08\u9910\u5385\u5206\u7c7b\uff0c\u8fd4\u56de\u5b57\u6bb5categoryCode\uff09\uff1aCHINESE=\u4e2d\u9910, WESTERN=\u897f\u9910, BBQ=\u70e7\u70e4, HOTPOT=\u706b\u9505, LOCAL=\u5f53\u5730\u7279\u8272\n- common_status\uff08\u72b6\u6001\uff0c\u8fd4\u56de\u5b57\u6bb5status\uff09\uff1aACTIVE=\u542f\u7528, INACTIVE=\u505c\u7528")
     @GetMapping("/items/batch")
     public Result<List<Map<String, Object>>> getRestaurantsBatch(@RequestParam @Size(max = 500) List<Long> restaurantIds) {
         List<Map<String, Object>> results = restaurantIds.stream()
@@ -61,9 +61,9 @@ public class InternalRestaurantController {
         return Result.success(results);
     }
 
-    @ApiOperation("\u5904\u7406\u5ba1\u6279\u56de\u8c03\u7ed3\u679c")
+    @ApiOperation(value = "\u5904\u7406\u5ba1\u6279\u56de\u8c03\u7ed3\u679c", notes = "\u3010\u4ec5\u9650\u5185\u90e8Feign\u8c03\u7528\u3011\u63a5\u6536\u4f01\u5faeOA\u5ba1\u6279\u56de\u8c03\uff0c\u6309thirdNo\u5339\u914d\u9910\u5385\u5e76\u66f4\u65b0\u542f\u7528/\u7981\u7528\u72b6\u6001\u3002\u7531hl-callback-service\u901a\u8fc7MQ\u6d88\u8d39\u540e\u8c03\u7528\uff0c\u5e42\u7b49\u5904\u7406\u3002\n\n**\u5173\u8054\u5b57\u5178**\uff1a\n- approval_sp_status\uff08\u5ba1\u6279\u72b6\u6001\uff0c\u8bf7\u6c42\u5b57\u6bb5spStatus\uff09")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         restaurantService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java
index eb8164c..7c8961f 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java
@@ -26,7 +26,7 @@ public class RestaurantController {
 
     private final RestaurantService restaurantService;
 
-    @ApiOperation("创建餐厅")
+    @ApiOperation(value = "创建餐厅", notes = "新建餐厅资源，初始状态为草稿(status=0)。餐厅没有价格日历，费用通过产品报价中的费用项管理。需走企微审批流程上架。\n\n**关联字典**：\n- restaurant_category：餐厅分类（表单选择）\n- cuisine_type：菜系类型（表单多选）\n- environment_type：环境类型（表单多选）\n- restaurant_facility：餐厅设施（表单多选）\n\n**纯文本字段**：\n- cityName：城市名称（手动输入，如「拉萨」「海拉尔」）")
     @PostMapping("/item")
     public Result<RestaurantVO> createRestaurant(
             @ApiParam("餐厅创建请求") @Valid @RequestBody RestaurantCreateRequest request,
@@ -35,19 +35,19 @@ public class RestaurantController {
         return Result.success(restaurantService.createRestaurant(request, adminId));
     }
 
-    @ApiOperation("餐厅列表")
+    @ApiOperation(value = "餐厅列表", notes = "分页查询餐厅列表，支持按名称、状态、分类、城市等条件筛选。\n\n**关联字典**：\n- restaurant_category：餐厅分类（筛选+列表显示）\n- cuisine_type：菜系类型（列表显示）\n- environment_type：环境类型（列表显示）\n- restaurant_facility：餐厅设施（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<RestaurantListVO>> listRestaurants(@ApiParam("餐厅查询请求") @Valid RestaurantQueryRequest query) {
         return Result.success(restaurantService.listRestaurants(query));
     }
 
-    @ApiOperation("餐厅详情")
+    @ApiOperation(value = "餐厅详情", notes = "获取餐厅完整信息，包含素材URL、标签、富文本介绍等。\n\n**关联字典**：\n- restaurant_category：餐厅分类（详情显示）\n- cuisine_type：菜系类型（详情显示）\n- environment_type：环境类型（详情显示）\n- restaurant_facility：餐厅设施（详情显示）")
     @GetMapping("/item/{restaurantId}")
     public Result<RestaurantVO> getRestaurant(@ApiParam("餐厅ID") @PathVariable Long restaurantId) {
         return Result.success(restaurantService.getRestaurant(restaurantId));
     }
 
-    @ApiOperation("更新餐厅")
+    @ApiOperation(value = "更新餐厅", notes = "更新餐厅基本信息，不改变当前状态。\n\n**关联字典**：\n- restaurant_category：餐厅分类（表单选择）\n- cuisine_type：菜系类型（表单多选）\n- environment_type：环境类型（表单多选）\n- restaurant_facility：餐厅设施（表单多选）\n\n**纯文本字段**：\n- cityName：城市名称（手动输入）")
     @PutMapping("/item/{restaurantId}")
     public Result<RestaurantVO> updateRestaurant(
             @ApiParam("餐厅ID") @PathVariable Long restaurantId,
@@ -57,7 +57,7 @@ public class RestaurantController {
         return Result.success(restaurantService.updateRestaurant(restaurantId, request, adminId));
     }
 
-    @ApiOperation("删除餐厅")
+    @ApiOperation(value = "删除餐厅", notes = "软删除餐厅。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/item/{restaurantId}")
     public Result<Void> deleteRestaurant(
             @ApiParam("餐厅ID") @PathVariable Long restaurantId,
@@ -68,7 +68,7 @@ public class RestaurantController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。")
     @PostMapping("/item/{restaurantId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("餐厅ID") @PathVariable Long restaurantId,
@@ -80,7 +80,7 @@ public class RestaurantController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("上下架切换")
+    @ApiOperation(value = "上下架切换", notes = "直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/item/{restaurantId}/status")
     public Result<Void> updateStatus(
             @ApiParam("餐厅ID") @PathVariable Long restaurantId,
@@ -91,7 +91,7 @@ public class RestaurantController {
         return Result.success();
     }
 
-    @ApiOperation("批量上下架")
+    @ApiOperation(value = "批量上下架", notes = "批量修改多个餐厅的状态，跳过审批流程。")
     @PutMapping("/items/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("餐厅状态请求") @Valid @RequestBody RestaurantStatusRequest request,
@@ -103,7 +103,7 @@ public class RestaurantController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个餐厅。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/items/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java
index 05b1056..7f96d5a 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java
@@ -27,7 +27,7 @@ public class RestaurantTagController {
 
     private final RestaurantTagService tagService;
 
-    @ApiOperation("\u83b7\u53d6\u7ba1\u7406\u6807\u7b7e\u5217\u8868\uff08\u5206\u9875\uff09")
+    @ApiOperation(value = "\u83b7\u53d6\u7ba1\u7406\u6807\u7b7e\u5217\u8868\uff08\u5206\u9875\uff09", notes = "\u5206\u9875\u67e5\u8be2\u9910\u5385\u6807\u7b7e\u5e93\uff0c\u652f\u6301\u6309\u5173\u952e\u8bcd\u641c\u7d22\u3002\u5305\u542b\u9884\u8bbe\u6807\u7b7e\u548c\u81ea\u5b9a\u4e49\u6807\u7b7e\u3002")
     @GetMapping("/tags")
     public Result<PageResult<RestaurantTagVO>> listManagedTags(
             @ApiParam("\u9875\u7801") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class RestaurantTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("\u83b7\u53d6\u5168\u90e8\u6807\u7b7e")
+    @ApiOperation(value = "\u83b7\u53d6\u5168\u90e8\u6807\u7b7e", notes = "\u4e0d\u5206\u9875\u8fd4\u56de\u6240\u6709\u6807\u7b7e\uff0c\u7528\u4e8e\u9910\u5385\u7f16\u8f91\u65f6\u7684\u6807\u7b7e\u9009\u62e9\u4e0b\u62c9\u3002")
     @GetMapping("/tags/all")
     public Result<List<RestaurantTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("\u521b\u5efa\u7ba1\u7406\u6807\u7b7e")
+    @ApiOperation(value = "\u521b\u5efa\u7ba1\u7406\u6807\u7b7e", notes = "\u521b\u5efa\u9884\u8bbe\u6807\u7b7e\uff0c\u6807\u7b7e\u540d\u4e0d\u53ef\u91cd\u590d\u3002\u53ef\u6307\u5b9a\u989c\u8272(tagColor)\uff0c\u9ed8\u8ba4#409EFF\u3002")
     @PostMapping("/tag")
     public Result<RestaurantTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class RestaurantTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("\u89e3\u6790\u81ea\u5b9a\u4e49\u6807\u7b7e")
+    @ApiOperation(value = "\u89e3\u6790\u81ea\u5b9a\u4e49\u6807\u7b7e", notes = "\u6309\u540d\u79f0\u67e5\u627e\u6216\u81ea\u52a8\u521b\u5efa\u6807\u7b7e\u3002\u7528\u4e8e\u9910\u5385\u7f16\u8f91\u65f6\u5feb\u901f\u8f93\u5165\u65b0\u6807\u7b7e\u3002")
     @PostMapping("/tag/adhoc")
     public Result<RestaurantTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class RestaurantTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("\u7f16\u8f91\u6807\u7b7e")
+    @ApiOperation(value = "\u7f16\u8f91\u6807\u7b7e", notes = "\u4fee\u6539\u6807\u7b7e\u540d\u79f0\u6216\u989c\u8272\uff0c\u6240\u6709\u5173\u8054\u9910\u5385\u81ea\u52a8\u751f\u6548\u3002")
     @PutMapping("/tag/{tagId}")
     public Result<RestaurantTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class RestaurantTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("\u5220\u9664\u6807\u7b7e")
+    @ApiOperation(value = "\u5220\u9664\u6807\u7b7e", notes = "\u5220\u9664\u6807\u7b7e\u5e76\u89e3\u9664\u6240\u6709\u9910\u5385\u4e0e\u8be5\u6807\u7b7e\u7684\u5173\u8054\u3002")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("\u66f4\u65b0\u9910\u5385\u6807\u7b7e")
+    @ApiOperation(value = "\u66f4\u65b0\u9910\u5385\u6807\u7b7e", notes = "\u5168\u91cf\u66ff\u6362\u6307\u5b9a\u9910\u5385\u7684\u6807\u7b7e\u5217\u8868\u3002\u4f20\u5165tagIds\u4e3a\u6700\u7ec8\u5173\u8054\u7684\u6807\u7b7eID\u5217\u8868\uff0c\u4e3a\u7a7a\u5219\u6e05\u9664\u6240\u6709\u6807\u7b7e\u3002")
     @PutMapping("/item/{restaurantId}/tags")
     public Result<Void> updateRestaurantTags(
             @ApiParam("餐厅ID") @PathVariable Long restaurantId,
@@ -87,7 +87,7 @@ public class RestaurantTagController {
         return Result.success();
     }
 
-    @ApiOperation("\u6279\u91cf\u6253\u6807\u7b7e")
+    @ApiOperation(value = "\u6279\u91cf\u6253\u6807\u7b7e", notes = "\u5bf9\u591a\u4e2a\u9910\u5385\u6279\u91cf\u6dfb\u52a0/\u79fb\u9664\u6807\u7b7e\u3002\u589e\u91cf\u64cd\u4f5c\uff0c\u4e0d\u5f71\u54cd\u672a\u6307\u5b9a\u7684\u6807\u7b7e\u3002")
     @PutMapping("/items/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java
index dbe9f19..a28ef38 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java
@@ -17,7 +17,7 @@ import java.util.List;
 /**
  * C端景区内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  */
-@Api(tags = "【内部接口】小程序景区（Feign调用）")
+@Api(tags = "【内部接口】小程序景区（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/scenic")
 @RequiredArgsConstructor
@@ -25,21 +25,21 @@ public class InternalMpScenicController {
 
     private final ScenicSpotService scenicSpotService;
 
-    @ApiOperation("C端景区列表")
+    @ApiOperation(value = "C端景区列表", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用。强制status=1只返回已上架景区，支持分页、城市筛选和关键词搜索。C端用户通过小程序间接访问。\n\ncityName为纯文本筛选字段，非字典。")
     @GetMapping("/list")
     public Result<PageResult<ScenicSpotListVO>> listScenic(ScenicSpotQueryRequest query) {
         query.setStatus(1);
         return Result.success(scenicSpotService.listSpots(query));
     }
 
-    @ApiOperation("C端景区详情")
+    @ApiOperation(value = "C端景区详情", notes = "【仅限内部Feign调用】供mp-service获取景区完整详情，包含封面、轮播图、标签、季节内容、富文本介绍、坐标等。注意：不限制status，由BFF层校验是否展示。")
     @GetMapping("/{scenicId}")
     public Result<ScenicSpotVO> getScenicDetail(@PathVariable Long scenicId) {
         ScenicSpotVO vo = scenicSpotService.getSpot(scenicId);
         return Result.success(vo);
     }
 
-    @ApiOperation("C端附近景区")
+    @ApiOperation(value = "C端附近景区", notes = "【仅限内部Feign调用】根据指定景区的坐标查询附近的景区列表。radius为搜索半径(km,默认50)，limit为最大返回数(默认10)。按距离排序，返回名称、封面、距离等信息。")
     @GetMapping("/{scenicId}/nearby")
     public Result<List<NearbyScenicVO>> getNearbyScenic(
             @PathVariable Long scenicId,

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java
index a902ee1..9f47695 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java
@@ -22,7 +22,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】景区（Feign调用）")
+@Api(tags = "【内部接口】景区（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/scenic")
 @RequiredArgsConstructor
@@ -31,7 +31,7 @@ public class InternalScenicController {
     private final ScenicSpotService spotService;
     private final ScenicPriceCalendarService priceService;
 
-    @ApiOperation("获取景区简要信息")
+    @ApiOperation(value = "获取景区简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个景区的简要信息，返回ID、名称、荣誉称号、城市、状态。不存在时返回错误。\n\n**关联字典**：\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/spot/{scenicId}")
     public Result<Map<String, Object>> getSpotBrief(@PathVariable Long scenicId) {
         ScenicSpot spot = spotService.getSpotEntity(scenicId);
@@ -47,7 +47,7 @@ public class InternalScenicController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取景区简要信息")
+    @ApiOperation(value = "批量获取景区简要信息", notes = "【仅限内部Feign调用】批量获取景区简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询行程节点绑定的景区资源。\n\n**关联字典**：\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/spots/batch")
     public Result<List<Map<String, Object>>> getSpotsBatch(@RequestParam @Size(max = 500) List<Long> scenicIds) {
         List<Map<String, Object>> results = scenicIds.stream()
@@ -67,7 +67,7 @@ public class InternalScenicController {
         return Result.success(results);
     }
 
-    @ApiOperation("查询某日价格")
+    @ApiOperation(value = "查询某日价格", notes = "【仅限内部Feign调用】查询景区指定日期的价格日历信息，包含成本价、售价、库存、状态。date格式为yyyy-MM-dd。供产品服务报价计算和库存校验使用。")
     @GetMapping("/spot/{scenicId}/price/{date}")
     public Result<PriceCalendarDayVO> getPriceForDate(
             @PathVariable Long scenicId,
@@ -76,7 +76,7 @@ public class InternalScenicController {
         return Result.success(price);
     }
 
-    @ApiOperation("判断某日是否可售")
+    @ApiOperation(value = "判断某日是否可售", notes = "【仅限内部Feign调用】判断景区指定日期是否可售（价格日历存在且状态为启用且库存>0）。供订单服务下单前校验使用。")
     @GetMapping("/spot/{scenicId}/available/{date}")
     public Result<Boolean> isAvailable(
             @PathVariable Long scenicId,
@@ -84,7 +84,7 @@ public class InternalScenicController {
         return Result.success(priceService.isAvailable(scenicId, LocalDate.parse(date)));
     }
 
-    @ApiOperation("扣减库存")
+    @ApiOperation(value = "扣减库存", notes = "【仅限内部Feign调用】扣减景区指定日期的库存数量。下单成功时由订单服务调用。库存不足时返回false。使用乐观锁防止超卖。")
     @PutMapping("/spot/{scenicId}/stock/deduct")
     public Result<Boolean> deductStock(
             @PathVariable Long scenicId,
@@ -94,7 +94,7 @@ public class InternalScenicController {
         return Result.success(success);
     }
 
-    @ApiOperation("恢复库存")
+    @ApiOperation(value = "恢复库存", notes = "【仅限内部Feign调用】恢复景区指定日期的库存数量。订单取消或退款时由订单服务调用，将之前扣减的库存加回。")
     @PutMapping("/spot/{scenicId}/stock/restore")
     public Result<Void> restoreStock(
             @PathVariable Long scenicId,
@@ -104,9 +104,9 @@ public class InternalScenicController {
         return Result.success();
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配景区并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         spotService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java
index 8e2b1cb..62d7de0 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java
@@ -25,7 +25,7 @@ public class ScenicPriceCalendarController {
 
     private final ScenicPriceCalendarService priceService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询景区的每日价格和可售状态。返回指定年月中所有已设置价格的日期，未设置的日期不返回。用于前端日历组件渲染。")
     @GetMapping("/spot/{scenicId}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -34,7 +34,7 @@ public class ScenicPriceCalendarController {
         return Result.success(priceService.getPriceCalendar(scenicId, year, month));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格", notes = "在指定日期范围内批量设置成本价、库存和可售状态。支持weekdayOnly/weekendOnly/selectedWeekdays过滤特定星期，支持excludeDates排除特定日期。已有价格的日期会被覆盖更新。")
     @PutMapping("/spot/{scenicId}/prices")
     public Result<Void> batchSetPrices(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -43,7 +43,7 @@ public class ScenicPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改可售状态")
+    @ApiOperation(value = "批量修改可售状态", notes = "批量修改指定日期范围内的可售状态，不影响价格和库存。status=0不可售，status=1可售。用于临时关闭/开放某些日期的售卖。")
     @PutMapping("/spot/{scenicId}/prices/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -52,7 +52,7 @@ public class ScenicPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量清除价格")
+    @ApiOperation(value = "批量清除价格", notes = "删除指定日期范围内的所有价格记录。删除后该日期范围将显示为未设置状态。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/spot/{scenicId}/prices")
     public Result<Void> deletePrices(
             @ApiParam("景区ID") @PathVariable Long scenicId,

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java
index 8933ec2..ab7ad78 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java
@@ -22,13 +22,13 @@ public class ScenicSeasonController {
 
     private final ScenicSeasonService seasonService;
 
-    @ApiOperation("获取景区全部季节内容")
+    @ApiOperation(value = "获取景区全部季节内容", notes = "返回景区的所有季节内容列表（春/夏/秋/冬）。季节内容是景区独有功能，其他资源类型没有此概念。每个季节可设置独立的封面、轮播图、亮点描述和游玩攻略。")
     @GetMapping("/spot/{scenicId}/seasons")
     public Result<List<ScenicSeasonVO>> getSeasons(@ApiParam("景区ID") @PathVariable Long scenicId) {
         return Result.success(seasonService.getSeasons(scenicId));
     }
 
-    @ApiOperation("保存/更新季节内容")
+    @ApiOperation(value = "保存/更新季节内容", notes = "创建或更新指定景区的季节内容。seasonType为季节标识（如spring/summer/autumn/winter）。如果该季节已存在则更新，不存在则创建。支持设置季节别名（如「樱花季」）、月份范围、独立封面和轮播图。")
     @PutMapping("/spot/{scenicId}/season/{seasonType}")
     public Result<ScenicSeasonVO> saveSeason(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -39,7 +39,7 @@ public class ScenicSeasonController {
         return Result.success(seasonService.saveSeason(scenicId, seasonType, request, adminId));
     }
 
-    @ApiOperation("删除季节内容")
+    @ApiOperation(value = "删除季节内容", notes = "删除指定景区的某个季节内容，同时清理关联的素材引用。")
     @DeleteMapping("/spot/{scenicId}/season/{seasonType}")
     public Result<Void> deleteSeason(
             @ApiParam("景区ID") @PathVariable Long scenicId,

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java
index b8aff01..c2da355 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java
@@ -26,7 +26,7 @@ public class ScenicSpotController {
 
     private final ScenicSpotService spotService;
 
-    @ApiOperation("创建景区")
+    @ApiOperation(value = "创建景区", notes = "新建一个景区资源，初始状态为草稿(status=0)。创建后需通过「提交启用审批」接口走企微OA审批流程才能上架。支持富文本字段（featureIntro/detailContent等），素材ID从素材库获取。\n\n**关联字典**：\n- scenic_facility：景区设施（表单多选）\n- scenic_honor：景区荣誉（表单多选）")
     @PostMapping("/spot")
     public Result<ScenicSpotVO> createSpot(
             @ApiParam("景区创建请求") @Valid @RequestBody ScenicSpotCreateRequest request,
@@ -35,19 +35,19 @@ public class ScenicSpotController {
         return Result.success(spotService.createSpot(request, adminId));
     }
 
-    @ApiOperation("景区列表")
+    @ApiOperation(value = "景区列表", notes = "分页查询景区列表，支持按名称关键词、状态(0草稿/1上架/2下架)、城市等条件筛选。返回列表摘要信息（不含富文本详情），按sortOrder倒序+创建时间倒序排列。\n\n**关联字典**：\n- scenic_facility：景区设施（列表显示）\n- scenic_honor：景区荣誉（列表显示）")
     @GetMapping("/spots")
     public Result<PageResult<ScenicSpotListVO>> listSpots(@ApiParam("景区查询请求") @Valid ScenicSpotQueryRequest query) {
         return Result.success(spotService.listSpots(query));
     }
 
-    @ApiOperation("景区详情")
+    @ApiOperation(value = "景区详情", notes = "获取景区完整信息，包含富文本内容、素材URL、标签列表、季节内容等。素材ID会自动解析为OSS访问地址。\n\n**关联字典**：\n- scenic_facility：景区设施（详情显示）\n- scenic_honor：景区荣誉（详情显示）")
     @GetMapping("/spot/{scenicId}")
     public Result<ScenicSpotVO> getSpot(@ApiParam("景区ID") @PathVariable Long scenicId) {
         return Result.success(spotService.getSpot(scenicId));
     }
 
-    @ApiOperation("更新景区")
+    @ApiOperation(value = "更新景区", notes = "更新景区基本信息和富文本内容。更新不会改变当前状态。如果景区已上架，修改后仍保持上架状态，无需重新审批。\n\n**关联字典**：\n- scenic_facility：景区设施（表单多选）\n- scenic_honor：景区荣誉（表单多选）")
     @PutMapping("/spot/{scenicId}")
     public Result<ScenicSpotVO> updateSpot(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -57,7 +57,7 @@ public class ScenicSpotController {
         return Result.success(spotService.updateSpot(scenicId, request, adminId));
     }
 
-    @ApiOperation("删除景区")
+    @ApiOperation(value = "删除景区", notes = "软删除景区（设置deleted_at）。仅SUPER_ADMIN角色或创建者本人可删除。已上架的景区需先下架再删除。删除后会同时清理关联的素材引用。")
     @DeleteMapping("/spot/{scenicId}")
     public Result<Void> deleteSpot(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -68,7 +68,7 @@ public class ScenicSpotController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交审批申请。targetStatus=1表示申请上架，targetStatus=2表示申请下架。提交后景区进入PENDING_APPROVAL状态，企微审批通过/拒绝后通过回调自动更新状态。返回企微审批单号spNo。同一景区不可重复提交未完成的审批。")
     @PostMapping("/spot/{scenicId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -80,7 +80,7 @@ public class ScenicSpotController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("上下架切换")
+    @ApiOperation(value = "上下架切换", notes = "直接修改景区状态（跳过审批流程），仅限SUPER_ADMIN使用。普通管理员应使用「提交启用/禁用审批」接口。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/spot/{scenicId}/status")
     public Result<Void> updateStatus(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -91,7 +91,7 @@ public class ScenicSpotController {
         return Result.success();
     }
 
-    @ApiOperation("批量上下架")
+    @ApiOperation(value = "批量上下架", notes = "批量修改多个景区的状态。scenicIds为景区ID列表（字符串格式），status为目标状态。跳过审批流程，适用于批量管理场景。")
     @PutMapping("/spots/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("景区状态请求") @Valid @RequestBody ScenicStatusRequest request,
@@ -103,7 +103,7 @@ public class ScenicSpotController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个景区。权限校验同单个删除：仅SUPER_ADMIN或创建者可操作。部分失败不影响其他景区的删除。")
     @DeleteMapping("/spots/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java
index eda0e91..1410edc 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java
@@ -27,7 +27,7 @@ public class ScenicTagController {
 
     private final ScenicTagService tagService;
 
-    @ApiOperation("获取管理标签列表（分页）")
+    @ApiOperation(value = "获取管理标签列表（分页）", notes = "分页查询景区标签库中的所有标签，支持按关键词搜索。标签分为预设标签（管理员创建）和自定义标签（adhoc接口创建），此接口返回全部类型。")
     @GetMapping("/tags")
     public Result<PageResult<ScenicTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class ScenicTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("获取全部标签")
+    @ApiOperation(value = "获取全部标签", notes = "不分页返回所有标签，用于景区编辑时的标签选择下拉列表。")
     @GetMapping("/tags/all")
     public Result<List<ScenicTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建管理标签")
+    @ApiOperation(value = "创建管理标签", notes = "创建预设标签，标签名不可重复。可指定颜色(tagColor)，默认为#409EFF。预设标签在标签管理页面展示和维护。")
     @PostMapping("/tag")
     public Result<ScenicTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class ScenicTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "输入标签名称，如果已存在则直接返回，不存在则自动创建。用于景区编辑时快速输入新标签，避免先到标签管理页面创建。")
     @PostMapping("/tag/adhoc")
     public Result<ScenicTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class ScenicTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("编辑标签")
+    @ApiOperation(value = "编辑标签", notes = "修改标签名称或颜色。修改后所有关联此标签的景区会自动生效。")
     @PutMapping("/tag/{tagId}")
     public Result<ScenicTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class ScenicTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并自动解除所有景区与该标签的关联关系。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("更新景区标签")
+    @ApiOperation(value = "更新景区标签", notes = "全量替换指定景区的标签列表。传入tagIds为该景区最终要关联的标签ID列表，为空则清除所有标签。")
     @PutMapping("/spot/{scenicId}/tags")
     public Result<Void> updateScenicTags(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -87,7 +87,7 @@ public class ScenicTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量打标签")
+    @ApiOperation(value = "批量打标签", notes = "对多个景区批量添加或移除标签。addTagIds为要添加的标签，removeTagIds为要移除的标签，两者可同时使用。增量操作，不影响未指定的标签。")
     @PutMapping("/spots/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {

`hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java
index 95c02bf..4125c0d 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java
@@ -17,7 +17,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】增值服务（Feign调用）")
+@Api(tags = "【内部接口】增值服务（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/service")
 @RequiredArgsConstructor
@@ -25,7 +25,7 @@ public class InternalServiceController {
 
     private final ServiceItemService serviceItemService;
 
-    @ApiOperation("获取服务简要信息")
+    @ApiOperation(value = "获取服务简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个增值服务的简要信息，返回ID、名称、分类编码、计费类型、是否收费、状态。不存在时返回错误。\n\n**关联字典**：\n- service_unit（计费单位，返回字段billingType）：PER_PERSON=元/人, PER_TIME=元/次, PER_DAY=元/天, PER_VEHICLE=元/台, FIXED=固定金额\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/item/{serviceId}")
     public Result<Map<String, Object>> getServiceBrief(@PathVariable Long serviceId) {
         ServiceItem item = serviceItemService.getServiceItemEntity(serviceId);
@@ -42,7 +42,7 @@ public class InternalServiceController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取服务简要信息")
+    @ApiOperation(value = "批量获取服务简要信息", notes = "【仅限内部Feign调用】批量获取增值服务简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询产品关联的服务项。\n\n**关联字典**：\n- service_unit（计费单位，返回字段billingType）：PER_PERSON=元/人, PER_TIME=元/次, PER_DAY=元/天, PER_VEHICLE=元/台, FIXED=固定金额\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/items/batch")
     public Result<List<Map<String, Object>>> getServiceBatch(@RequestParam @Size(max = 500) List<Long> serviceIds) {
         List<Map<String, Object>> results = serviceIds.stream()
@@ -63,9 +63,9 @@ public class InternalServiceController {
         return Result.success(results);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配增值服务并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         serviceItemService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java
index 6750979..52e1bb9 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java
@@ -26,7 +26,7 @@ public class ServiceItemController {
 
     private final ServiceItemService serviceItemService;
 
-    @ApiOperation("创建服务")
+    @ApiOperation(value = "创建增值服务", notes = "新建增值服务项目（如保险、签证代办、接送机等），初始状态为草稿(status=0)。支持免费(isPaid=false)和付费两种模式，付费服务有独立的价格日历。需走企微审批上架。\n\n**关联字典**：\n- service_category：服务分类（表单选择）\n- billing_type_service：服务计费方式（表单选择）\n- service_unit：服务计量单位（表单选择）")
     @PostMapping("/item")
     public Result<ServiceItemVO> createServiceItem(
             @ApiParam("服务创建请求") @Valid @RequestBody ServiceCreateRequest request,
@@ -35,19 +35,19 @@ public class ServiceItemController {
         return Result.success(serviceItemService.createServiceItem(request, adminId));
     }
 
-    @ApiOperation("服务列表")
+    @ApiOperation(value = "增值服务列表", notes = "分页查询增值服务列表，支持按名称、状态、分类等条件筛选。\n\n**关联字典**：\n- service_category：服务分类（筛选+列表显示）\n- billing_type_service：服务计费方式（列表显示）\n- service_unit：服务计量单位（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<ServiceItemListVO>> listServiceItems(@ApiParam("服务查询请求") @Valid ServiceQueryRequest query) {
         return Result.success(serviceItemService.listServiceItems(query));
     }
 
-    @ApiOperation("服务详情")
+    @ApiOperation(value = "增值服务详情", notes = "获取增值服务完整信息，包含素材URL、标签、计费方式等。\n\n**关联字典**：\n- service_category：服务分类（详情显示）\n- billing_type_service：服务计费方式（详情显示）\n- service_unit：服务计量单位（详情显示）")
     @GetMapping("/item/{serviceId}")
     public Result<ServiceItemVO> getServiceItem(@ApiParam("服务ID") @PathVariable Long serviceId) {
         return Result.success(serviceItemService.getServiceItem(serviceId));
     }
 
-    @ApiOperation("更新服务")
+    @ApiOperation(value = "更新增值服务", notes = "更新增值服务基本信息，不改变当前状态。\n\n**关联字典**：\n- service_category：服务分类（表单选择）\n- billing_type_service：服务计费方式（表单选择）\n- service_unit：服务计量单位（表单选择）")
     @PutMapping("/item/{serviceId}")
     public Result<ServiceItemVO> updateServiceItem(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -57,7 +57,7 @@ public class ServiceItemController {
         return Result.success(serviceItemService.updateServiceItem(serviceId, request, adminId));
     }
 
-    @ApiOperation("删除服务")
+    @ApiOperation(value = "删除增值服务", notes = "软删除增值服务。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/item/{serviceId}")
     public Result<Void> deleteServiceItem(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -68,7 +68,7 @@ public class ServiceItemController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。")
     @PostMapping("/item/{serviceId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -80,7 +80,7 @@ public class ServiceItemController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("启用/禁用切换")
+    @ApiOperation(value = "启用/禁用切换", notes = "直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/item/{serviceId}/status")
     public Result<Void> updateStatus(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -91,7 +91,7 @@ public class ServiceItemController {
         return Result.success();
     }
 
-    @ApiOperation("批量启用/禁用")
+    @ApiOperation(value = "批量启用/禁用", notes = "批量修改多个增值服务的状态，跳过审批流程。")
     @PutMapping("/items/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("服务状态请求") @Valid @RequestBody ServiceStatusRequest request,
@@ -103,7 +103,7 @@ public class ServiceItemController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个增值服务。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/items/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java
index e96654d..a2f52d3 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java
@@ -25,7 +25,7 @@ public class ServicePriceCalendarController {
 
     private final ServicePriceCalendarService priceService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询增值服务的每日价格和可售状态。仅付费服务(isPaid=true)需要设置价格日历。")
     @GetMapping("/item/{serviceId}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -34,7 +34,7 @@ public class ServicePriceCalendarController {
         return Result.success(priceService.getPriceCalendar(serviceId, year, month));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格", notes = "在指定日期范围内批量设置服务的成本价和可售状态。")
     @PutMapping("/item/{serviceId}/prices")
     public Result<Void> batchSetPrices(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -43,7 +43,7 @@ public class ServicePriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改可售状态")
+    @ApiOperation(value = "批量修改可售状态", notes = "批量修改日期范围内的可售状态，不影响价格。")
     @PutMapping("/item/{serviceId}/prices/batch-status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -52,7 +52,7 @@ public class ServicePriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量清除价格")
+    @ApiOperation(value = "批量清除价格", notes = "删除指定日期范围内的价格记录。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/item/{serviceId}/prices")
     public Result<Void> deletePrices(
             @ApiParam("服务ID") @PathVariable Long serviceId,

`hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java
index cf3865a..5dca328 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java
@@ -27,7 +27,7 @@ public class ServiceTagController {
 
     private final ServiceTagService tagService;
 
-    @ApiOperation("获取管理标签列表（分页）")
+    @ApiOperation(value = "获取管理标签列表（分页）", notes = "分页查询增值服务标签库，支持按关键词搜索。")
     @GetMapping("/tags")
     public Result<PageResult<ServiceTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class ServiceTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("获取全部标签")
+    @ApiOperation(value = "获取全部标签", notes = "不分页返回所有标签，用于服务编辑时的标签选择。")
     @GetMapping("/tags/all")
     public Result<List<ServiceTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建管理标签")
+    @ApiOperation(value = "创建管理标签", notes = "创建预设标签，标签名不可重复。")
     @PostMapping("/tag")
     public Result<ServiceTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class ServiceTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "按名称查找或自动创建标签。")
     @PostMapping("/tag/adhoc")
     public Result<ServiceTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class ServiceTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("编辑标签")
+    @ApiOperation(value = "编辑标签", notes = "修改标签名称或颜色，所有关联服务自动生效。")
     @PutMapping("/tag/{tagId}")
     public Result<ServiceTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class ServiceTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并解除所有服务与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("更新服务标签")
+    @ApiOperation(value = "更新服务标签", notes = "全量替换指定服务的标签列表。")
     @PutMapping("/item/{serviceId}/tags")
     public Result<Void> updateServiceTags(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -87,7 +87,7 @@ public class ServiceTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量打标签")
+    @ApiOperation(value = "批量打标签", notes = "对多个服务批量添加/移除标签。增量操作。")
     @PutMapping("/items/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {

`hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java
index 7c8bb51..ce700da 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java
@@ -19,7 +19,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】服务人员（Feign调用）")
+@Api(tags = "【内部接口】服务人员（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/staff")
 @RequiredArgsConstructor
@@ -28,7 +28,7 @@ public class InternalStaffController {
     private final StaffService staffService;
     private final StaffMapper staffMapper;
 
-    @ApiOperation("获取人员简要信息")
+    @ApiOperation(value = "获取人员简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个服务人员的简要信息，返回ID、姓名、人员类型、手机号、状态。不存在时返回错误。\n\n**关联字典**：\n- staff_type（人员类型，返回字段staffType）：GUIDE=导游, DRIVER=司机, PHOTOGRAPHER=摄影师, CHEF=厨师\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/{staffId}")
     public Result<Map<String, Object>> getStaffBrief(@PathVariable Long staffId) {
         Staff staff = staffService.getStaffEntity(staffId);
@@ -44,7 +44,7 @@ public class InternalStaffController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取人员简要信息")
+    @ApiOperation(value = "批量获取人员简要信息", notes = "【仅限内部Feign调用】批量获取服务人员简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询团批关联的服务人员。\n\n**关联字典**：\n- staff_type（人员类型，返回字段staffType）：GUIDE=导游, DRIVER=司机, PHOTOGRAPHER=摄影师, CHEF=厨师\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/batch")
     public Result<List<Map<String, Object>>> getStaffBatch(@RequestParam @Size(max = 500) List<Long> staffIds) {
         List<Map<String, Object>> results = staffIds.stream()
@@ -64,7 +64,7 @@ public class InternalStaffController {
         return Result.success(results);
     }
 
-    @ApiOperation("按人员类型查询")
+    @ApiOperation(value = "按人员类型查询", notes = "【仅限内部Feign调用】按staffType查询第一个匹配的服务人员。staffType如：GUIDE(导游)、DRIVER(司机)、PHOTOGRAPHER(摄影师)等。未找到时返回null。\n\n**关联字典**：\n- staff_type（人员类型，请求参数+返回字段staffType）：GUIDE=导游, DRIVER=司机, PHOTOGRAPHER=摄影师, CHEF=厨师\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/by-type/{staffType}")
     public Result<Map<String, Object>> getStaffByType(@PathVariable String staffType) {
         Staff staff = staffService.getStaffByType(staffType);
@@ -80,9 +80,9 @@ public class InternalStaffController {
         return Result.success(brief);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配服务人员并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         staffService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();
@@ -91,7 +91,7 @@ public class InternalStaffController {
     /**
      * Batch get staff basic info by comma-separated IDs (for product-service batch staff snapshot).
      */
-    @ApiOperation("批量获取人员基本信息(逗号分隔ID)")
+    @ApiOperation(value = "批量获取人员基本信息(逗号分隔ID)", notes = "【仅限内部Feign调用】通过逗号分隔的ID字符串批量获取人员基本信息（含staffId、name、phone、staffType、coverMaterialId）。供产品服务团批人员快照使用。与/batch接口不同，此接口接收逗号分隔字符串而非数组。\n\n**关联字典**：\n- staff_type（人员类型，返回字段staffType）：GUIDE=导游, DRIVER=司机, PHOTOGRAPHER=摄影师, CHEF=厨师")
     @GetMapping("/batch-basic")
     public Result<List<Map<String, Object>>> batchGetStaffBasic(@RequestParam String staffIds) {
         List<Long> ids = Arrays.stream(staffIds.split(","))
@@ -122,7 +122,7 @@ public class InternalStaffController {
      * List available staff (status=1), optionally filter by staffType.
      * Used by admin batch staff selection dropdown.
      */
-    @ApiOperation("列出可用人员(用于下拉选择)")
+    @ApiOperation(value = "列出可用人员(用于下拉选择)", notes = "【仅限内部Feign调用】列出所有status=1的可用服务人员，可按staffType筛选。按sortOrder和staffId排序。供管理后台团批分配人员的下拉选择框使用。\n\n**关联字典**：\n- staff_type（人员类型，请求参数+返回字段staffType）：GUIDE=导游, DRIVER=司机, PHOTOGRAPHER=摄影师, CHEF=厨师")
     @GetMapping("/list-available")
     public Result<List<Map<String, Object>>> listAvailableStaff(
             @RequestParam(required = false) String staffType) {

`hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java
index f90638f..be01710 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java
@@ -24,7 +24,7 @@ public class StaffController {
 
     private final StaffService staffService;
 
-    @ApiOperation("创建服务人员")
+    @ApiOperation(value = "创建服务人员", notes = "新建服务人员（导游/领队/摄影师/助理等）。人员类型(staffType)决定了其在价格日历中的归类。需走企微审批上架后才能被产品引用。\n\n**关联字典**：\n- staff_type：人员类型（表单选择）\n- guide_level：导游等级（表单选择）\n- driver_license_type：驾照类型（表单选择）\n- language：语言能力（表单多选）\n- guide_specialty：导游专长（表单多选）\n- guide_service_area：服务区域（表单多选）")
     @PostMapping
     public Result<StaffVO> createStaff(@ApiParam("服务人员创建请求") @Valid @RequestBody StaffCreateRequest request,
                                         HttpServletRequest httpRequest) {
@@ -32,19 +32,19 @@ public class StaffController {
         return Result.success(staffService.createStaff(request, adminId));
     }
 
-    @ApiOperation("服务人员列表")
+    @ApiOperation(value = "服务人员列表", notes = "分页查询服务人员列表，支持按姓名、状态、人员类型等条件筛选。\n\n**关联字典**：\n- staff_type：人员类型（筛选+列表显示）\n- guide_level：导游等级（列表显示）\n- driver_license_type：驾照类型（列表显示）\n- language：语言能力（列表显示）\n- guide_specialty：导游专长（列表显示）\n- guide_service_area：服务区域（列表显示）")
     @GetMapping("/list")
     public Result<PageResult<StaffListVO>> listStaff(@ApiParam("服务人员查询请求") @Valid StaffQueryRequest query) {
         return Result.success(staffService.listStaff(query));
     }
 
-    @ApiOperation("服务人员详情")
+    @ApiOperation(value = "服务人员详情", notes = "获取服务人员完整信息，包含素材URL、标签、技能描述等。\n\n**关联字典**：\n- staff_type：人员类型（详情显示）\n- guide_level：导游等级（详情显示）\n- driver_license_type：驾照类型（详情显示）\n- language：语言能力（详情显示）\n- guide_specialty：导游专长（详情显示）\n- guide_service_area：服务区域（详情显示）")
     @GetMapping("/{staffId}")
     public Result<StaffVO> getStaff(@ApiParam("人员ID") @PathVariable Long staffId) {
         return Result.success(staffService.getStaff(staffId));
     }
 
-    @ApiOperation("更新服务人员")
+    @ApiOperation(value = "更新服务人员", notes = "更新服务人员基本信息，不改变当前状态。\n\n**关联字典**：\n- staff_type：人员类型（表单选择）\n- guide_level：导游等级（表单选择）\n- driver_license_type：驾照类型（表单选择）\n- language：语言能力（表单多选）\n- guide_specialty：导游专长（表单多选）\n- guide_service_area：服务区域（表单多选）")
     @PutMapping("/{staffId}")
     public Result<StaffVO> updateStaff(@ApiParam("人员ID") @PathVariable Long staffId,
                                         @ApiParam("服务人员更新请求") @Valid @RequestBody StaffUpdateRequest request,
@@ -53,7 +53,7 @@ public class StaffController {
         return Result.success(staffService.updateStaff(staffId, request, adminId));
     }
 
-    @ApiOperation("删除服务人员")
+    @ApiOperation(value = "删除服务人员", notes = "软删除服务人员。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/{staffId}")
     public Result<Void> deleteStaff(@ApiParam("人员ID") @PathVariable Long staffId, HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);
@@ -62,7 +62,7 @@ public class StaffController {
         return Result.success();
     }
 
-    @ApiOperation("提交审批")
+    @ApiOperation(value = "提交审批", notes = "向企微OA提交人员启用/禁用审批。targetStatus=1申请启用，targetStatus=2申请禁用。返回审批单号spNo。")
     @PostMapping("/{staffId}/submit-approval")
     public Result<Map<String, String>> submitApproval(@ApiParam("人员ID") @PathVariable Long staffId,
                                                        @ApiParam("审批提交请求体") @Valid @RequestBody ApprovalSubmitRequest request,
@@ -72,7 +72,7 @@ public class StaffController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("更新状态")
+    @ApiOperation(value = "更新状态", notes = "直接修改人员状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=启用，2=禁用。")
     @PutMapping("/{staffId}/status")
     public Result<Void> updateStatus(@ApiParam("人员ID") @PathVariable Long staffId,
                                       @ApiParam("状态请求体") @Valid @RequestBody StaffStatusRequest request,
@@ -82,14 +82,14 @@ public class StaffController {
         return Result.success();
     }
 
-    @ApiOperation("批量更新状态")
+    @ApiOperation(value = "批量更新状态", notes = "批量修改多个服务人员的状态，跳过审批流程。")
     @PutMapping("/batch/status")
     public Result<Void> batchUpdateStatus(@ApiParam("批量状态请求体") @Valid @RequestBody StaffStatusRequest request) {
         staffService.batchUpdateStatus(request.getStaffIds(), request.getStatus());
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个服务人员。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/batch")
     public Result<Void> batchDelete(@ApiParam("批量删除请求体") @Valid @RequestBody StaffBatchDeleteRequest request,
                                      HttpServletRequest httpRequest) {

`hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java
index 2993bef..a762de1 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java
@@ -27,7 +27,7 @@ public class StaffPriceCalendarController {
 
     private final StaffPriceCalendarService priceCalendarService;
 
-    @ApiOperation("查询价格日历（按人员类型）")
+    @ApiOperation(value = "查询价格日历（按人员类型）", notes = "按月查询指定人员类型的每日服务费用和可调度状态。注意：价格日历按人员类型维度管理，非按个人维度。同一类型的所有人员共享同一套价格。\n\n**关联字典**：\n- staff_type（人员类型）→ staffType路径参数")
     @GetMapping("/type/{staffType}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(
             @ApiParam("人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER") @PathVariable String staffType,
@@ -36,7 +36,7 @@ public class StaffPriceCalendarController {
         return Result.success(priceCalendarService.getPriceCalendar(staffType, year, month));
     }
 
-    @ApiOperation("批量设置价格（按人员类型）")
+    @ApiOperation(value = "批量设置价格（按人员类型）", notes = "在指定日期范围内批量设置该类型人员的服务成本价和可调度状态。\n\n**关联字典**：\n- staff_type（人员类型）→ staffType路径参数")
     @PutMapping("/type/{staffType}/prices")
     public Result<Void> batchSetPrices(
             @ApiParam("人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER") @PathVariable String staffType,
@@ -45,7 +45,7 @@ public class StaffPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改调度状态（按人员类型）")
+    @ApiOperation(value = "批量修改调度状态（按人员类型）", notes = "批量修改日期范围内的可调度状态，不影响价格。\n\n**关联字典**：\n- staff_type（人员类型）→ staffType路径参数")
     @PutMapping("/type/{staffType}/prices/batch-status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER") @PathVariable String staffType,
@@ -54,7 +54,7 @@ public class StaffPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("清除价格日历（按人员类型）")
+    @ApiOperation(value = "清除价格日历（按人员类型）", notes = "删除指定日期范围内该类型人员的价格记录。日期格式：yyyy-MM-dd。\n\n**关联字典**：\n- staff_type（人员类型）→ staffType路径参数")
     @DeleteMapping("/type/{staffType}/prices")
     public Result<Void> deletePrices(
             @ApiParam("人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER") @PathVariable String staffType,

`hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java
index beceb5f..ff68d2c 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java
@@ -26,7 +26,7 @@ public class StaffTagController {
 
     private final StaffTagService tagService;
 
-    @ApiOperation("预设标签列表（分页）")
+    @ApiOperation(value = "预设标签列表（分页）", notes = "分页查询服务人员标签库，支持按关键词搜索。")
     @GetMapping("/tags")
     public Result<PageResult<StaffTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -35,13 +35,13 @@ public class StaffTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("全部标签列表")
+    @ApiOperation(value = "全部标签列表", notes = "不分页返回所有标签，用于人员编辑时的标签选择。")
     @GetMapping("/tags/all")
     public Result<List<StaffTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建标签")
+    @ApiOperation(value = "创建标签", notes = "创建预设标签，标签名不可重复。")
     @PostMapping("/tag")
     public Result<StaffTagVO> createTag(@ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
                                          HttpServletRequest httpRequest) {
@@ -49,7 +49,7 @@ public class StaffTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "按名称查找或自动创建标签。")
     @PostMapping("/tag/adhoc")
     public Result<StaffTagVO> resolveAdHocTag(@ApiParam("标签名称请求体") @Valid @RequestBody TagCreateRequest request,
                                                HttpServletRequest httpRequest) {
@@ -57,21 +57,21 @@ public class StaffTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("更新标签")
+    @ApiOperation(value = "更新标签", notes = "修改标签名称或颜色。")
     @PutMapping("/tag/{tagId}")
     public Result<StaffTagVO> updateTag(@ApiParam("标签ID") @PathVariable Long tagId,
                                          @ApiParam("标签更新请求") @Valid @RequestBody TagUpdateRequest request) {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并解除所有人员与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("设置人员标签")
+    @ApiOperation(value = "设置人员标签", notes = "全量替换指定人员的标签列表。")
     @PutMapping("/{staffId}/tags")
     public Result<Void> updateStaffTags(@ApiParam("人员ID") @PathVariable Long staffId,
                                          @ApiParam("标签ID列表请求") @Valid @RequestBody StaffTagUpdateRequest request) {
@@ -79,7 +79,7 @@ public class StaffTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量添加/移除标签")
+    @ApiOperation(value = "批量添加/移除标签", notes = "对多个人员批量添加/移除标签。增量操作。")
     @PutMapping("/batch/tags")
     public Result<Void> batchUpdateTags(@ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {
         tagService.batchUpdateTags(request.getStaffIds(), request.getAddTagIds(), request.getRemoveTagIds());

`hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java
index 5467d19..e827b51 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java
@@ -17,7 +17,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】备品（Feign调用）")
+@Api(tags = "【内部接口】备品（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/supplies")
 @RequiredArgsConstructor
@@ -25,7 +25,7 @@ public class InternalSuppliesController {
 
     private final SuppliesService suppliesService;
 
-    @ApiOperation("获取备品简要信息")
+    @ApiOperation(value = "获取备品简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个备品的简要信息，返回ID、名称、分类编码、计费类型、状态。不存在时返回错误。\n\n**关联字典**：\n- supplies_category（备品分类，返回字段categoryCode）：CAMPING=露营, CLOTHING=服装, EQUIPMENT=装备, SAFETY=安全\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/item/{suppliesId}")
     public Result<Map<String, Object>> getSuppliesBrief(@PathVariable Long suppliesId) {
         SuppliesItem item = suppliesService.getSuppliesEntity(suppliesId);
@@ -41,7 +41,7 @@ public class InternalSuppliesController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取备品简要信息")
+    @ApiOperation(value = "批量获取备品简要信息", notes = "【仅限内部Feign调用】批量获取备品简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询产品关联的备品资源。\n\n**关联字典**：\n- supplies_category（备品分类，返回字段categoryCode）：CAMPING=露营, CLOTHING=服装, EQUIPMENT=装备, SAFETY=安全\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/items/batch")
     public Result<List<Map<String, Object>>> getSuppliesBatch(@RequestParam @Size(max = 500) List<Long> suppliesIds) {
         List<Map<String, Object>> results = suppliesIds.stream()
@@ -61,9 +61,9 @@ public class InternalSuppliesController {
         return Result.success(results);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配备品并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         suppliesService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java
index 435f28b..964e6fc 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java
@@ -26,7 +26,7 @@ public class SuppliesController {
 
     private final SuppliesService suppliesService;
 
-    @ApiOperation("创建备品")
+    @ApiOperation(value = "创建备品", notes = "新建备品资源（帐篷、睡袋、炊具等物资），初始状态为草稿(status=0)。需走企微审批上架。支持按件(PER_ITEM)和按人(PER_PERSON)计费。\n\n**关联字典**：\n- supplies_category：备品分类（表单选择）\n- billing_type：计费方式（表单选择）")
     @PostMapping("/item")
     public Result<SuppliesVO> createSupplies(
             @ApiParam("备品创建请求") @Valid @RequestBody SuppliesCreateRequest request,
@@ -35,19 +35,19 @@ public class SuppliesController {
         return Result.success(suppliesService.createSupplies(request, adminId));
     }
 
-    @ApiOperation("备品列表")
+    @ApiOperation(value = "备品列表", notes = "分页查询备品列表，支持按名称、状态、分类等条件筛选。\n\n**关联字典**：\n- supplies_category：备品分类（筛选+列表显示）\n- billing_type：计费方式（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<SuppliesListVO>> listSupplies(@ApiParam("备品查询请求") @Valid SuppliesQueryRequest query) {
         return Result.success(suppliesService.listSupplies(query));
     }
 
-    @ApiOperation("备品详情")
+    @ApiOperation(value = "备品详情", notes = "获取备品完整信息，包含素材URL、标签等。\n\n**关联字典**：\n- supplies_category：备品分类（详情显示）\n- billing_type：计费方式（详情显示）")
     @GetMapping("/item/{suppliesId}")
     public Result<SuppliesVO> getSupplies(@ApiParam("备品ID") @PathVariable Long suppliesId) {
         return Result.success(suppliesService.getSupplies(suppliesId));
     }
 
-    @ApiOperation("更新备品")
+    @ApiOperation(value = "更新备品", notes = "更新备品基本信息，不改变当前状态。\n\n**关联字典**：\n- supplies_category：备品分类（表单选择）\n- billing_type：计费方式（表单选择）")
     @PutMapping("/item/{suppliesId}")
     public Result<SuppliesVO> updateSupplies(
             @ApiParam("备品ID") @PathVariable Long suppliesId,
@@ -57,7 +57,7 @@ public class SuppliesController {
         return Result.success(suppliesService.updateSupplies(suppliesId, request, adminId));
     }
 
-    @ApiOperation("删除备品")
+    @ApiOperation(value = "删除备品", notes = "软删除备品。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/item/{suppliesId}")
     public Result<Void> deleteSupplies(
             @ApiParam("备品ID") @PathVariable Long suppliesId,
@@ -68,7 +68,7 @@ public class SuppliesController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。")
     @PostMapping("/item/{suppliesId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("备品ID") @PathVariable Long suppliesId,
@@ -80,7 +80,7 @@ public class SuppliesController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("上下架切换")
+    @ApiOperation(value = "上下架切换", notes = "直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/item/{suppliesId}/status")
     public Result<Void> updateStatus(
             @ApiParam("备品ID") @PathVariable Long suppliesId,
@@ -91,7 +91,7 @@ public class SuppliesController {
         return Result.success();
     }
 
-    @ApiOperation("批量上下架")
+    @ApiOperation(value = "批量上下架", notes = "批量修改多个备品的状态，跳过审批流程。")
     @PutMapping("/items/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("备品状态请求") @Valid @RequestBody SuppliesStatusRequest request,
@@ -103,7 +103,7 @@ public class SuppliesController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个备品。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/items/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java
index 7529058..8095ade 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java
@@ -27,7 +27,7 @@ public class SuppliesTagController {
 
     private final SuppliesTagService tagService;
 
-    @ApiOperation("获取管理标签列表（分页）")
+    @ApiOperation(value = "获取管理标签列表（分页）", notes = "分页查询备品标签库，支持按关键词搜索。")
     @GetMapping("/tags")
     public Result<PageResult<SuppliesTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class SuppliesTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("获取全部标签")
+    @ApiOperation(value = "获取全部标签", notes = "不分页返回所有标签，用于备品编辑时的标签选择下拉。")
     @GetMapping("/tags/all")
     public Result<List<SuppliesTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建管理标签")
+    @ApiOperation(value = "创建管理标签", notes = "创建预设标签，标签名不可重复。")
     @PostMapping("/tag")
     public Result<SuppliesTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class SuppliesTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "按名称查找或自动创建标签。")
     @PostMapping("/tag/adhoc")
     public Result<SuppliesTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class SuppliesTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("编辑标签")
+    @ApiOperation(value = "编辑标签", notes = "修改标签名称或颜色，所有关联备品自动生效。")
     @PutMapping("/tag/{tagId}")
     public Result<SuppliesTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class SuppliesTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并解除所有备品与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("更新备品标签")
+    @ApiOperation(value = "更新备品标签", notes = "全量替换指定备品的标签列表。")
     @PutMapping("/item/{suppliesId}/tags")
     public Result<Void> updateSuppliesTags(
             @ApiParam("备品ID") @PathVariable Long suppliesId,
@@ -87,7 +87,7 @@ public class SuppliesTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量打标签")
+    @ApiOperation(value = "批量打标签", notes = "对多个备品批量添加/移除标签。增量操作。")
     @PutMapping("/items/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {

`hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java
index 4e672d1..a0dc396 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java
@@ -17,7 +17,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】车型（Feign调用）")
+@Api(tags = "【内部接口】车型（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/vehicle")
 @RequiredArgsConstructor
@@ -25,7 +25,7 @@ public class InternalVehicleController {
 
     private final VehicleModelService vehicleModelService;
 
-    @ApiOperation("获取车型简要信息")
+    @ApiOperation(value = "获取车型简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个车型的简要信息，返回ID、名称、车辆类型、品牌、座位数、状态。不存在时返回错误。\n\n**关联字典**：\n- vehicle_type（车辆类型，返回字段vehicleType）：CAR=小轿车, SUV=越野车, VAN=商务车, BUS=大巴, MINIBUS=中巴\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/model/{vehicleId}")
     public Result<Map<String, Object>> getVehicleBrief(@PathVariable Long vehicleId) {
         VehicleModel model = vehicleModelService.getVehicleEntity(vehicleId);
@@ -42,7 +42,7 @@ public class InternalVehicleController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取车型简要信息")
+    @ApiOperation(value = "批量获取车型简要信息", notes = "【仅限内部Feign调用】批量获取车型简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询行程关联的车辆资源。\n\n**关联字典**：\n- vehicle_type（车辆类型，返回字段vehicleType）：CAR=小轿车, SUV=越野车, VAN=商务车, BUS=大巴, MINIBUS=中巴\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/models/batch")
     public Result<List<Map<String, Object>>> getVehicleBatch(@RequestParam @Size(max = 500) List<Long> vehicleIds) {
         List<Map<String, Object>> results = vehicleIds.stream()
@@ -63,7 +63,7 @@ public class InternalVehicleController {
         return Result.success(results);
     }
 
-    @ApiOperation("按车辆类型查询车辆")
+    @ApiOperation(value = "按车辆类型查询车辆", notes = "【仅限内部Feign调用】按vehicleType查询第一个匹配的车型。vehicleType如：SEDAN(轿车)、SUV、MPV、BUS(大巴)、MINIBUS(中巴)等。未找到时返回null。\n\n**关联字典**：\n- vehicle_type（车辆类型，请求参数+返回字段vehicleType）：CAR=小轿车, SUV=越野车, VAN=商务车, BUS=大巴, MINIBUS=中巴\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/model/by-type/{vehicleType}")
     public Result<Map<String, Object>> getVehicleByType(@PathVariable String vehicleType) {
         VehicleModel model = vehicleModelService.getVehicleByType(vehicleType);
@@ -80,7 +80,7 @@ public class InternalVehicleController {
         return Result.success(brief);
     }
 
-    @ApiOperation("按名称查询车辆")
+    @ApiOperation(value = "按名称查询车辆", notes = "【仅限内部Feign调用】按车型名称精确查询车辆信息。未找到时返回null。供产品服务通过名称关联车型使用。\n\n**关联字典**：\n- vehicle_type（车辆类型，返回字段vehicleType）：CAR=小轿车, SUV=越野车, VAN=商务车, BUS=大巴, MINIBUS=中巴\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/model/by-name/{name}")
     public Result<Map<String, Object>> getVehicleByName(@PathVariable String name) {
         VehicleModel model = vehicleModelService.getVehicleByName(name);
@@ -97,9 +97,9 @@ public class InternalVehicleController {
         return Result.success(brief);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配车型并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         vehicleModelService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java
index de59d9f..37797fd 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java
@@ -25,7 +25,7 @@ public class VehicleModelController {
 
     private final VehicleModelService vehicleModelService;
 
-    @ApiOperation("创建车型")
+    @ApiOperation(value = "创建车型", notes = "新建车型资源（如7座商务车、14座中巴等），初始状态为草稿(status=0)。车型有独立的价格日历用于报价计算。需走企微审批上架。\n\n**关联字典**：\n- vehicle_type：车辆类型（表单选择）")
     @PostMapping("/model")
     public Result<VehicleModelVO> createVehicle(@ApiParam("车型创建请求") @Valid @RequestBody VehicleCreateRequest request,
                                                  HttpServletRequest httpRequest) {
@@ -33,26 +33,26 @@ public class VehicleModelController {
         return Result.success(vehicleModelService.createVehicle(request, adminId));
     }
 
-    @ApiOperation("车型列表")
+    @ApiOperation(value = "车型列表", notes = "分页查询车型列表，支持按名称、状态、车辆类型等条件筛选。\n\n**关联字典**：\n- vehicle_type：车辆类型（筛选+列表显示）")
     @GetMapping("/models")
     public Result<PageResult<VehicleModelListVO>> listVehicles(@ApiParam("车型查询请求") @Valid VehicleQueryRequest query) {
         return Result.success(vehicleModelService.listVehicles(query));
     }
 
-    @ApiOperation("车型全量列表（不分页，用于下拉选择）")
+    @ApiOperation(value = "车型全量列表（不分页，用于下拉选择）", notes = "返回所有车型列表，可选按状态筛选。适用于产品编排时选择车型的下拉选择框。不分页返回全部数据。\n\n**关联字典**：\n- vehicle_type：车辆类型（列表显示）")
     @GetMapping("/models/all")
     public Result<List<VehicleModelListVO>> listAllVehicles(
             @ApiParam("状态筛选：1=上架") @RequestParam(required = false) Integer status) {
         return Result.success(vehicleModelService.listAllVehicles(status));
     }
 
-    @ApiOperation("车型详情")
+    @ApiOperation(value = "车型详情", notes = "获取车型完整信息，包含座位数、品牌、素材URL、标签等。\n\n**关联字典**：\n- vehicle_type：车辆类型（详情显示）")
     @GetMapping("/model/{vehicleId}")
     public Result<VehicleModelVO> getVehicle(@ApiParam("车型ID") @PathVariable Long vehicleId) {
         return Result.success(vehicleModelService.getVehicle(vehicleId));
     }
 
-    @ApiOperation("更新车型")
+    @ApiOperation(value = "更新车型", notes = "更新车型基本信息，不改变当前状态。\n\n**关联字典**：\n- vehicle_type：车辆类型（表单选择）")
     @PutMapping("/model/{vehicleId}")
     public Result<VehicleModelVO> updateVehicle(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                                  @ApiParam("车型更新请求") @Valid @RequestBody VehicleUpdateRequest request,
@@ -61,7 +61,7 @@ public class VehicleModelController {
         return Result.success(vehicleModelService.updateVehicle(vehicleId, request, adminId));
     }
 
-    @ApiOperation("删除车型")
+    @ApiOperation(value = "删除车型", notes = "软删除车型。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/model/{vehicleId}")
     public Result<Void> deleteVehicle(@ApiParam("车型ID") @PathVariable Long vehicleId, HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);
@@ -70,7 +70,7 @@ public class VehicleModelController {
         return Result.success();
     }
 
-    @ApiOperation("提交审批")
+    @ApiOperation(value = "提交审批", notes = "向企微OA提交车型启用/禁用审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。")
     @PostMapping("/model/{vehicleId}/submit-approval")
     public Result<Map<String, String>> submitApproval(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                                        @ApiParam("审批提交请求体") @Valid @RequestBody ApprovalSubmitRequest request,
@@ -80,7 +80,7 @@ public class VehicleModelController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("更新状态")
+    @ApiOperation(value = "更新状态", notes = "直接修改车型状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/model/{vehicleId}/status")
     public Result<Void> updateStatus(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                       @ApiParam("状态请求体") @Valid @RequestBody VehicleStatusRequest request,
@@ -90,7 +90,7 @@ public class VehicleModelController {
         return Result.success();
     }
 
-    @ApiOperation("批量更新状态")
+    @ApiOperation(value = "批量更新状态", notes = "批量修改多个车型的状态，跳过审批流程。")
     @PutMapping("/models/batch/status")
     public Result<Void> batchUpdateStatus(@ApiParam("批量状态请求体") @Valid @RequestBody VehicleStatusRequest request,
                                            HttpServletRequest httpRequest) {
@@ -98,7 +98,7 @@ public class VehicleModelController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个车型。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/models/batch")
     public Result<Void> batchDelete(@ApiParam("批量删除请求体") @Valid @RequestBody VehicleBatchDeleteRequest request,
                                      HttpServletRequest httpRequest) {

`hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java
index 52a68eb..c1bcfba 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java
@@ -27,7 +27,7 @@ public class VehiclePriceCalendarController {
 
     private final VehiclePriceCalendarService priceCalendarService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询车型的每日租赁价格和可调度状态。")
     @GetMapping("/model/{vehicleId}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                                      @ApiParam("年份") @RequestParam @Min(2020) @Max(2100) Integer year,
@@ -35,7 +35,7 @@ public class VehiclePriceCalendarController {
         return Result.success(priceCalendarService.getPriceCalendar(vehicleId, year, month));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格", notes = "在指定日期范围内批量设置车型的租赁成本价和可调度状态。")
     @PutMapping("/model/{vehicleId}/prices")
     public Result<Void> batchSetPrices(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                         @ApiParam("价格日历设置请求") @Valid @RequestBody PriceCalendarSetRequest request) {
@@ -43,7 +43,7 @@ public class VehiclePriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改调度状态")
+    @ApiOperation(value = "批量修改调度状态", notes = "批量修改日期范围内车型的可调度状态，不影响价格。")
     @PutMapping("/model/{vehicleId}/prices/batch-status")
     public Result<Void> batchUpdateStatus(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                            @ApiParam("价格日历状态请求") @Valid @RequestBody PriceCalendarStatusRequest request) {
@@ -51,7 +51,7 @@ public class VehiclePriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("清除价格日历")
+    @ApiOperation(value = "清除价格日历", notes = "删除指定日期范围内车型的价格记录。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/model/{vehicleId}/prices")
     public Result<Void> deletePrices(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                       @ApiParam("开始日期") @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate startDate,

`hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java` (M)

接口变更 diff：

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java
index a7a1b49..b2ad988 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java
@@ -26,7 +26,7 @@ public class VehicleTagController {
 
     private final VehicleTagService tagService;
 
-    @ApiOperation("预设标签列表（分页）")
+    @ApiOperation(value = "预设标签列表（分页）", notes = "分页查询车型标签库，支持按关键词搜索。")
     @GetMapping("/tags")
     public Result<PageResult<VehicleTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -35,13 +35,13 @@ public class VehicleTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("全部标签列表")
+    @ApiOperation(value = "全部标签列表", notes = "不分页返回所有标签，用于车型编辑时的标签选择。")
     @GetMapping("/tags/all")
     public Result<List<VehicleTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建标签")
+    @ApiOperation(value = "创建标签", notes = "创建预设标签，标签名不可重复。")
     @PostMapping("/tag")
     public Result<VehicleTagVO> createTag(@ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
                                            HttpServletRequest httpRequest) {
@@ -49,7 +49,7 @@ public class VehicleTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "按名称查找或自动创建标签。")
     @PostMapping("/tag/adhoc")
     public Result<VehicleTagVO> resolveAdHocTag(@ApiParam("标签名称请求体") @Valid @RequestBody TagCreateRequest request,
                                                  HttpServletRequest httpRequest) {
@@ -57,21 +57,21 @@ public class VehicleTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("更新标签")
+    @ApiOperation(value = "更新标签", notes = "修改标签名称或颜色。")
     @PutMapping("/tag/{tagId}")
     public Result<VehicleTagVO> updateTag(@ApiParam("标签ID") @PathVariable Long tagId,
                                            @ApiParam("标签更新请求") @Valid @RequestBody TagUpdateRequest request) {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并解除所有车型与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("设置车型标签")
+    @ApiOperation(value = "设置车型标签", notes = "全量替换指定车型的标签列表。")
     @PutMapping("/model/{vehicleId}/tags")
     public Result<Void> updateVehicleTags(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                            @ApiParam("标签ID列表请求") @Valid @RequestBody VehicleTagUpdateRequest request) {
@@ -79,7 +79,7 @@ public class VehicleTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量添加/移除标签")
+    @ApiOperation(value = "批量添加/移除标签", notes = "对多个车型批量添加/移除标签。增量操作。")
     @PutMapping("/models/batch/tags")
     public Result<Void> batchUpdateTags(@ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {
         tagService.batchUpdateTags(request.getVehicleIds(), request.getAddTagIds(), request.getRemoveTagIds());

`hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java` (M)

接口变更 diff：

diff --git a/hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java b/hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java
index 1781646..ad503eb 100644
--- a/hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java
+++ b/hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java
@@ -25,19 +25,19 @@ public class AdminReviewController {
 
     private final ReviewService reviewService;
 
-    @ApiOperation("评价列表(支持好中差评/有图/有视频筛选)")
+    @ApiOperation(value = "评价列表(支持好中差评/有图/有视频筛选)", notes = "分页查询全部评价（含待审核/已通过/已拒绝），支持按评价等级、是否有图/视频、目标类型筛选\n\n**关联字典**：\n- review_status：评价审核状态（列表筛选+显示）\n- rating_level：评价等级（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<ReviewListVO>> listReviews(@ApiParam("评价查询条件") ReviewQueryRequest request) {
         return Result.success(reviewService.listReviews(request));
     }
 
-    @ApiOperation("评价详情")
+    @ApiOperation(value = "评价详情", notes = "**关联字典**：\n- review_status：评价审核状态（显示）\n- rating_level：评价等级（显示）")
     @GetMapping("/{reviewId}")
     public Result<ReviewVO> getReviewDetail(@ApiParam("评价ID") @PathVariable Long reviewId) {
         return Result.success(reviewService.getReviewDetail(reviewId));
     }
 
-    @ApiOperation("通过评价")
+    @ApiOperation(value = "通过评价", notes = "审核通过评价，通过后评价在小程序端公开展示。状态流转：PENDING_REVIEW → APPROVED")
     @PostMapping("/{reviewId}/approve")
     public Result<Void> approve(@ApiParam("评价ID") @PathVariable Long reviewId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -47,7 +47,7 @@ public class AdminReviewController {
         return Result.success();
     }
 
-    @ApiOperation("拒绝评价")
+    @ApiOperation(value = "拒绝评价", notes = "审核拒绝评价，需填写拒绝原因。拒绝后评价不公开展示。状态流转：PENDING_REVIEW → REJECTED")
     @PostMapping("/{reviewId}/reject")
     public Result<Void> reject(@ApiParam("评价ID") @PathVariable Long reviewId,
                                @ApiParam("拒绝请求") @Valid @RequestBody RejectRequest body,
@@ -59,7 +59,7 @@ public class AdminReviewController {
         return Result.success();
     }
 
-    @ApiOperation("覆盖通过(机器拒绝的)")
+    @ApiOperation(value = "覆盖通过(机器拒绝的)", notes = "对阿里云内容审核自动拒绝的评价进行人工覆盖通过。状态流转：AUTO_REJECTED → APPROVED")
     @PostMapping("/{reviewId}/override-approve")
     public Result<Void> overrideApprove(@ApiParam("评价ID") @PathVariable Long reviewId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -69,7 +69,8 @@ public class AdminReviewController {
         return Result.success();
     }
 
-    @ApiOperation("回复评价(每条评价仅可回复一次)")
+    @ApiOperation(value = "回复评价(每条评价仅可回复一次)",
+            notes = "管理员回复用户评价，回复内容在小程序端公开展示。每条评价仅允许回复一次，不可修改。\n\n**权限**：需管理员登录。")
     @PostMapping("/{reviewId}/reply")
     public Result<Void> adminReply(@ApiParam("评价ID") @PathVariable Long reviewId,
                                     @ApiParam("回复内容") @Valid @RequestBody AdminReplyRequest body,

`hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java` (M)

接口变更 diff：

diff --git a/hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java b/hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java
index b3dd6a3..62fb7d0 100644
--- a/hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java
+++ b/hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java
@@ -19,7 +19,7 @@ import javax.validation.Valid;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "【内部接口】小程序评价（Feign调用）")
+@Api(tags = "【内部接口】小程序评价（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/review")
 @RequiredArgsConstructor
@@ -27,7 +27,7 @@ public class InternalMpReviewController {
 
     private final ReviewService reviewService;
 
-    @ApiOperation("创建评价(仅针对产品，每个订单仅可评价一次)")
+    @ApiOperation(value = "创建评价(仅针对产品，每个订单仅可评价一次)", notes = "**关联字典**：\n- review_status：评价审核状态（返回字段）\n- rating_level：评价等级（返回字段）")
     @PostMapping("/create")
     public Result<ReviewVO> createReview(@Valid @RequestBody CreateReviewRequest body,
                                          HttpServletRequest request) {
@@ -35,13 +35,14 @@ public class InternalMpReviewController {
         return Result.success(reviewService.createReview(userId, body));
     }
 
-    @ApiOperation("检查订单是否已评价")
+    @ApiOperation(value = "检查订单是否已评价",
+            notes = "内部服务间调用。检查指定订单是否已有评价记录，用于小程序端订单详情页控制评价入口的显示。")
     @GetMapping("/order/{orderId}/reviewed")
     public Result<Boolean> isOrderReviewed(@PathVariable Long orderId) {
         return Result.success(reviewService.isOrderReviewed(orderId));
     }
 
-    @ApiOperation("我的评价列表")
+    @ApiOperation(value = "我的评价列表", notes = "**关联字典**：\n- review_status：评价审核状态（显示）\n- rating_level：评价等级（显示）")
     @GetMapping("/my")
     public Result<PageResult<MpReviewVO>> getMyReviews(MpReviewQueryRequest query,
                                                         HttpServletRequest request) {
@@ -49,13 +50,13 @@ public class InternalMpReviewController {
         return Result.success(reviewService.getMyReviews(userId, query));
     }
 
-    @ApiOperation("某目标的已通过评价(公开，支持好中差评/有图/有视频筛选)")
+    @ApiOperation(value = "某目标的已通过评价(公开，支持好中差评/有图/有视频筛选)", notes = "**关联字典**：\n- rating_level：评价等级（筛选+显示）")
     @GetMapping("/target")
     public Result<PageResult<MpReviewVO>> getTargetReviews(@Valid TargetReviewQueryRequest query) {
         return Result.success(reviewService.getTargetReviews(query));
     }
 
-    @ApiOperation("关键词搜索评价(公开)")
+    @ApiOperation(value = "关键词搜索评价(公开)", notes = "**关联字典**：\n- rating_level：评价等级（显示）")
     @GetMapping("/search")
     public Result<PageResult<MpReviewVO>> searchReviews(
             @ApiParam("搜索关键词") @RequestParam String keyword,
@@ -66,14 +67,15 @@ public class InternalMpReviewController {
         return Result.success(reviewService.searchReviews(keyword, targetType, targetId, page, pageSize));
     }
 
-    @ApiOperation("首页精选评价")
+    @ApiOperation(value = "首页精选评价", notes = "**关联字典**：\n- rating_level：评价等级（显示）")
     @GetMapping("/featured")
     public Result<List<MpReviewVO>> getFeaturedReviews(
             @ApiParam("数量限制") @RequestParam(defaultValue = "5") Integer limit) {
         return Result.success(reviewService.getFeaturedReviews(limit));
     }
 
-    @ApiOperation("订单可评价目标列表")
+    @ApiOperation(value = "订单可评价目标列表",
+            notes = "内部服务间调用。返回订单关联的可评价目标（产品、定制师等），用于评价页面选择评价对象。已评价的目标不会重复出现。")
     @GetMapping("/order/{orderId}/reviewable-targets")
     public Result<List<Map<String, Object>>> getReviewableTargets(
             @PathVariable Long orderId, HttpServletRequest request) {
@@ -81,7 +83,8 @@ public class InternalMpReviewController {
         return Result.success(reviewService.getReviewableTargets(orderId, userId));
     }
 
-    @ApiOperation("点赞/取消点赞评价")
+    @ApiOperation(value = "点赞/取消点赞评价",
+            notes = "内部服务间调用。切换当前用户对评价的点赞状态（toggle），返回最新点赞状态和点赞总数。")
     @PostMapping("/{reviewId}/like")
     public Result<Map<String, Object>> toggleLike(@PathVariable Long reviewId,
                                                     HttpServletRequest request) {
@@ -89,7 +92,8 @@ public class InternalMpReviewController {
         return Result.success(reviewService.toggleLike(reviewId, userId));
     }
 
-    @ApiOperation("检查是否已点赞")
+    @ApiOperation(value = "检查是否已点赞",
+            notes = "内部服务间调用。检查当前用户是否已对指定评价点赞，用于小程序端渲染点赞按钮状态。")
     @GetMapping("/{reviewId}/like/check")
     public Result<Boolean> checkLiked(@PathVariable Long reviewId,
                                        HttpServletRequest request) {
@@ -97,7 +101,8 @@ public class InternalMpReviewController {
         return Result.success(reviewService.checkLiked(reviewId, userId));
     }
 
-    @ApiOperation("同步评价点赞数（供通用点赞服务回调）")
+    @ApiOperation(value = "同步评价点赞数（供通用点赞服务回调）",
+            notes = "内部服务间调用。通用点赞服务（user-service）发生点赞变化后回调此接口，同步更新评价表的点赞计数字段。")
     @PostMapping("/{reviewId}/sync-like-count")
     public Result<Void> syncLikeCount(@PathVariable Long reviewId,
                                        @RequestParam int likeCount) {

`hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java` (M)

接口变更 diff：

diff --git a/hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java b/hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java
index 0567412..7e5f1cb 100644
--- a/hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java
+++ b/hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java
@@ -21,7 +21,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
-@Api(tags = "【内部接口】评价统计（Feign调用）")
+@Api(tags = "【内部接口】评价统计（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/review")
 @RequiredArgsConstructor
@@ -29,14 +29,14 @@ public class InternalReviewController {
 
     private final ReviewService reviewService;
 
-    @ApiOperation("目标评价统计(平均分,数量)")
+    @ApiOperation(value = "目标评价统计(平均分,数量)", notes = "**关联字典**：\n- rating_level：评价等级（统计维度）")
     @GetMapping("/target-stats")
     public Result<ReviewStatsVO> getTargetStats(@RequestParam String targetType,
                                                  @RequestParam Long targetId) {
         return Result.success(reviewService.getTargetStats(targetType, targetId));
     }
 
-    @ApiOperation("目标已通过评价列表")
+    @ApiOperation(value = "目标已通过评价列表", notes = "**关联字典**：\n- rating_level：评价等级（显示）")
     @GetMapping("/target-list")
     public Result<PageResult<MpReviewVO>> getTargetReviews(
             @RequestParam String targetType,
@@ -46,7 +46,7 @@ public class InternalReviewController {
         return Result.success(reviewService.getTargetReviewsInternal(targetType, targetId, page, pageSize));
     }
 
-    @ApiOperation("批量目标评价统计(聚合多个targetId)")
+    @ApiOperation(value = "批量目标评价统计(聚合多个targetId)", notes = "**关联字典**：\n- rating_level：评价等级（统计维度）")
     @GetMapping("/stats-by-targets")
     public Result<ReviewStatsVO> getStatsByTargetIds(
             @RequestParam String targetType,
@@ -55,7 +55,7 @@ public class InternalReviewController {
         return Result.success(reviewService.getStatsByTargetIds(targetType, ids));
     }
 
-    @ApiOperation("批量目标已通过评价列表(聚合多个targetId)")
+    @ApiOperation(value = "批量目标已通过评价列表(聚合多个targetId)", notes = "**关联字典**：\n- rating_level：评价等级（显示）")
     @GetMapping("/reviews-by-targets")
     public Result<PageResult<MpReviewVO>> getReviewsByTargetIds(
             @RequestParam String targetType,
@@ -66,13 +66,13 @@ public class InternalReviewController {
         return Result.success(reviewService.getReviewsByTargetIds(targetType, ids, page, pageSize));
     }
 
-    @ApiOperation("产品精选评价(最高评分+最高点赞+统计)")
+    @ApiOperation(value = "产品精选评价(最高评分+最高点赞+统计)", notes = "**关联字典**：\n- rating_level：评价等级（显示）")
     @GetMapping("/product-highlights")
     public Result<Map<String, Object>> getProductHighlights(@RequestParam Long productId) {
         return Result.success(reviewService.getProductHighlightReviews(productId));
     }
 
-    @ApiOperation("定制师已通过评价列表")
+    @ApiOperation(value = "定制师已通过评价列表", notes = "**关联字典**：\n- rating_level：评价等级（筛选+显示）")
     @GetMapping("/customizer-reviews")
     public Result<PageResult<MpReviewVO>> getCustomizerReviews(
             @RequestParam Long customizerId,
@@ -82,7 +82,8 @@ public class InternalReviewController {
         return Result.success(reviewService.getCustomizerReviews(customizerId, page, pageSize, ratingLevel));
     }
 
-    @ApiOperation("定制师评价统计(总数/平均分/好评率)")
+    @ApiOperation(value = "定制师评价统计(总数/平均分/好评率)",
+            notes = "内部服务间调用。返回指定定制师的评价汇总统计：总评价数、平均评分、好评率等。用于定制师主页展示服务评价。")
     @GetMapping("/customizer-review-stats")
     public Result<java.util.Map<String, Object>> getCustomizerReviewStats(
             @RequestParam Long customizerId) {

`hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java` (M)

接口变更 diff：

diff --git a/hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java b/hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java
index 75b6a7a..0629ed1 100644
--- a/hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java
+++ b/hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java
@@ -33,7 +33,7 @@ public class BoardController {
 
     // ======================= Board CRUD =======================
 
-    @ApiOperation("获取可见看板列表")
+    @ApiOperation(value = "获取可见看板列表", notes = "返回当前管理员可见的看板列表：超级管理员可见所有看板，普通管理员仅可见自己创建的或作为成员的看板")
     @GetMapping("/boards")
     public Result<List<BoardVO>> getBoards(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -41,7 +41,7 @@ public class BoardController {
         return Result.success(boardService.getVisibleBoards(adminId, role));
     }
 
-    @ApiOperation("看板详情")
+    @ApiOperation(value = "看板详情", notes = "返回看板基本信息（名称、描述、创建者），不含任务数据。查看任务请使用「获取看板任务」接口")
     @GetMapping("/board/{boardId}")
     public Result<BoardVO> getBoardDetail(@ApiParam("看板ID") @PathVariable Long boardId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -49,7 +49,8 @@ public class BoardController {
         return Result.success(boardService.getBoardDetail(boardId, adminId, role));
     }
 
-    @ApiOperation("创建自定义看板")
+    @ApiOperation(value = "创建自定义看板",
+            notes = "创建自定义看板，自动添加创建者为看板成员，并创建默认状态列（待办、进行中、已完成）。\n\n**权限**：需管理员登录。")
     @OperationLog(value = "创建看板", module = "任务看板")
     @PostMapping("/board")
     public Result<BoardVO> createBoard(@ApiParam("创建看板请求") @Valid @RequestBody CreateBoardRequest req, HttpServletRequest request) {
@@ -57,7 +58,8 @@ public class BoardController {
         return Result.success(boardService.createBoard(req, adminId));
     }
 
-    @ApiOperation("更新看板")
+    @ApiOperation(value = "更新看板",
+            notes = "更新看板的名称和描述。仅看板创建者或超级管理员可操作。\n\n**权限**：需管理员登录，且为看板创建者或超级管理员。")
     @OperationLog(value = "编辑看板", module = "任务看板")
     @PutMapping("/board/{boardId}")
     public Result<BoardVO> updateBoard(@ApiParam("看板ID") @PathVariable Long boardId,
@@ -68,7 +70,7 @@ public class BoardController {
         return Result.success(boardService.updateBoard(boardId, req, adminId, role));
     }
 
-    @ApiOperation("删除看板")
+    @ApiOperation(value = "删除看板", notes = "删除看板及其下所有状态列和任务（级联删除）。仅看板创建者或超级管理员可操作")
     @OperationLog(value = "删除看板", module = "任务看板")
     @DeleteMapping("/board/{boardId}")
     public Result<Void> deleteBoard(@ApiParam("看板ID") @PathVariable Long boardId, HttpServletRequest request) {
@@ -80,13 +82,14 @@ public class BoardController {
 
     // ======================= Status columns =======================
 
-    @ApiOperation("获取看板状态列")
+    @ApiOperation(value = "获取看板状态列", notes = "返回看板的所有状态列（如待办、进行中、已完成），按排序字段升序排列。拖拽任务到不同状态列实现状态流转")
     @GetMapping("/board/{boardId}/statuses")
     public Result<List<BoardStatusVO>> getStatuses(@ApiParam("看板ID") @PathVariable Long boardId) {
         return Result.success(boardStatusService.getStatuses(boardId));
     }
 
-    @ApiOperation("创建状态列")
+    @ApiOperation(value = "创建状态列",
+            notes = "在看板中创建新的状态列（如测试中、待发布等），自动排到末尾。任务通过拖拽在不同状态列间流转。\n\n**权限**：需管理员登录且为看板成员。")
     @OperationLog(value = "新增状态列", module = "任务看板")
     @PostMapping("/board/{boardId}/status")
     public Result<BoardStatusVO> createStatus(@ApiParam("看板ID") @PathVariable Long boardId,
@@ -97,7 +100,8 @@ public class BoardController {
         return Result.success(boardStatusService.createStatus(boardId, req, adminId, role));
     }
 
-    @ApiOperation("更新状态列")
+    @ApiOperation(value = "更新状态列",
+            notes = "更新状态列的名称和颜色。\n\n**权限**：需管理员登录且为看板成员。")
     @OperationLog(value = "编辑状态列", module = "任务看板")
     @PutMapping("/status/{statusId}")
     public Result<BoardStatusVO> updateStatus(@ApiParam("状态列ID") @PathVariable Long statusId,
@@ -108,7 +112,7 @@ public class BoardController {
         return Result.success(boardStatusService.updateStatus(statusId, req, adminId, role));
     }
 
-    @ApiOperation("删除状态列")
+    @ApiOperation(value = "删除状态列", notes = "删除看板的状态列。如果状态列下有任务则不允许删除，需先移动或删除任务")
     @OperationLog(value = "删除状态列", module = "任务看板")
     @DeleteMapping("/status/{statusId}")
     public Result<Void> deleteStatus(@ApiParam("状态列ID") @PathVariable Long statusId,
@@ -119,7 +123,7 @@ public class BoardController {
         return Result.success();
     }
 
-    @ApiOperation("状态列排序")
+    @ApiOperation(value = "状态列排序", notes = "批量更新状态列的排序顺序。传入状态列ID数组，数组下标即为新的排序值。操作完成后通过WebSocket推送STATUS_REORDERED事件")
     @PutMapping("/board/{boardId}/status/sort")
     public Result<Void> sortStatuses(@ApiParam("看板ID") @PathVariable Long boardId,
                                      @ApiParam("状态列排序请求") @Valid @RequestBody StatusSortRequest req,
@@ -133,13 +137,14 @@ public class BoardController {
 
     // ======================= Board Members =======================
 
-    @ApiOperation("获取看板成员")
+    @ApiOperation(value = "获取看板成员", notes = "返回看板的所有成员列表，包含成员的管理员ID和姓名")
     @GetMapping("/board/{boardId}/members")
     public Result<List<BoardMemberVO>> getMembers(@ApiParam("看板ID") @PathVariable Long boardId) {
         return Result.success(boardMemberService.getMembers(boardId));
     }
 
-    @ApiOperation("添加成员")
+    @ApiOperation(value = "添加成员",
+            notes = "批量添加管理员为看板成员，成为成员后可以查看看板、创建和操作任务。\n\n**权限**：需管理员登录，且为看板创建者或超级管理员。")
     @OperationLog(value = "添加看板成员", module = "任务看板")
     @PostMapping("/board/{boardId}/members")
     public Result<Void> addMembers(@ApiParam("看板ID") @PathVariable Long boardId,
@@ -151,7 +156,7 @@ public class BoardController {
         return Result.success();
     }
 
-    @ApiOperation("移除成员")
+    @ApiOperation(value = "移除成员", notes = "从看板中移除指定成员。仅看板创建者或超级管理员可操作，不能移除创建者自己")
     @OperationLog(value = "移除看板成员", module = "任务看板")
     @DeleteMapping("/board/{boardId}/member/{targetAdminId}")
     public Result<Void> removeMember(@ApiParam("看板ID") @PathVariable Long boardId,

`hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java` (M)

接口变更 diff：

diff --git a/hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java b/hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java
index 8593e4d..c85aeca 100644
--- a/hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java
+++ b/hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java
@@ -31,7 +31,7 @@ public class TaskController {
 
     // ======================= Tasks =======================
 
-    @ApiOperation("获取看板任务(按状态分组)")
+    @ApiOperation(value = "获取看板任务(按状态分组)", notes = "返回看板下所有任务，按状态列分组。支持按优先级(HIGH/MEDIUM/LOW)和负责人筛选，每组内按排序值升序排列\n\n**关联字典**：\n- task_priority：任务优先级（列表筛选+显示）")
     @GetMapping("/board/{boardId}/tasks")
     public Result<List<BoardTasksVO>> getBoardTasks(@ApiParam("看板ID") @PathVariable Long boardId,
                                                      @ApiParam("优先级") @RequestParam(required = false) String priority,
@@ -42,7 +42,7 @@ public class TaskController {
         return Result.success(taskService.getBoardTasks(boardId, adminId, role, priority, assigneeId));
     }
 
-    @ApiOperation("任务详情")
+    @ApiOperation(value = "任务详情", notes = "返回任务完整信息，包含子任务列表、负责人信息、附件列表等\n\n**关联字典**：\n- task_priority：任务优先级（显示）")
     @GetMapping("/{taskId}")
     public Result<TaskVO> getTaskDetail(@ApiParam("任务ID") @PathVariable Long taskId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -50,7 +50,7 @@ public class TaskController {
         return Result.success(taskService.getTaskDetail(taskId, adminId, role));
     }
 
-    @ApiOperation("创建任务")
+    @ApiOperation(value = "创建任务", notes = "在指定看板和状态列下创建任务。创建成功后通过WebSocket推送TASK_CREATED事件，并通知被分配的负责人\n\n**关联字典**：\n- task_priority：任务优先级（创建时选择）")
     @OperationLog(value = "创建任务", module = "任务看板")
     @PostMapping
     public Result<TaskVO> createTask(@ApiParam("创建任务请求") @Valid @RequestBody CreateTaskRequest req, HttpServletRequest request) {
@@ -62,7 +62,8 @@ public class TaskController {
         return Result.success(vo);
     }
 
-    @ApiOperation("更新任务")
+    @ApiOperation(value = "更新任务",
+            notes = "更新任务的标题、描述、优先级、截止日期、负责人等信息。更新后通过WebSocket推送TASK_UPDATED事件，如果修改了负责人则额外通知新负责人。\n\n**权限**：需管理员登录且为看板成员。\n\n**关联字典**：\n- task_priority：任务优先级（编辑时选择）")
     @OperationLog(value = "编辑任务", module = "任务看板")
     @PutMapping("/{taskId}")
     public Result<TaskVO> updateTask(@ApiParam("任务ID") @PathVariable Long taskId,
@@ -78,7 +79,7 @@ public class TaskController {
         return Result.success(vo);
     }
 
-    @ApiOperation("变更任务状态")
+    @ApiOperation(value = "变更任务状态", notes = "将任务移动到指定状态列（拖拽操作），自动记录状态变更到时间线，并通过WebSocket推送TASK_STATUS_CHANGED事件")
     @PutMapping("/{taskId}/status")
     public Result<Void> changeStatus(@ApiParam("任务ID") @PathVariable Long taskId,
                                      @ApiParam("变更状态请求") @Valid @RequestBody ChangeStatusRequest req,
@@ -91,7 +92,7 @@ public class TaskController {
         return Result.success();
     }
 
-    @ApiOperation("任务排序")
+    @ApiOperation(value = "任务排序", notes = "更新任务在同一状态列内的排序位置，用于拖拽排序")
     @PutMapping("/{taskId}/sort")
     public Result<Void> sortTasks(@ApiParam("任务ID") @PathVariable Long taskId,
                                   @ApiParam("任务排序请求") @Valid @RequestBody TaskSortRequest req,
@@ -102,7 +103,8 @@ public class TaskController {
         return Result.success();
     }
 
-    @ApiOperation("删除任务")
+    @ApiOperation(value = "删除任务",
+            notes = "删除任务及其所有子任务、评论和时间线记录（级联删除）。删除后通过WebSocket推送TASK_DELETED事件。\n\n**权限**：需管理员登录且为看板成员。")
     @OperationLog(value = "删除任务", module = "任务看板")
     @DeleteMapping("/{taskId}")
     public Result<Void> deleteTask(@ApiParam("任务ID") @PathVariable Long taskId, HttpServletRequest request) {
@@ -117,7 +119,8 @@ public class TaskController {
 
     // ======================= Subtasks =======================
 
-    @ApiOperation("创建子任务")
+    @ApiOperation(value = "创建子任务",
+            notes = "在指定任务下创建子任务（待办项），用于拆分任务的执行步骤。子任务默认为未完成状态。\n\n**权限**：需管理员登录且为看板成员。")
     @PostMapping("/{taskId}/subtask")
     public Result<SubtaskVO> createSubtask(@ApiParam("任务ID") @PathVariable Long taskId,
                                             @ApiParam("创建子任务请求") @Valid @RequestBody CreateSubtaskRequest req,
@@ -128,7 +131,7 @@ public class TaskController {
         return Result.success(vo);
     }
 
-    @ApiOperation("切换子任务完成状态")
+    @ApiOperation(value = "切换子任务完成状态", notes = "切换子任务的完成/未完成状态（toggle），完成状态切换会自动记录到任务时间线")
     @PutMapping("/subtask/{subtaskId}/toggle")
     public Result<Void> toggleSubtask(@ApiParam("子任务ID") @PathVariable Long subtaskId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -137,7 +140,8 @@ public class TaskController {
         return Result.success();
     }
 
-    @ApiOperation("删除子任务")
+    @ApiOperation(value = "删除子任务",
+            notes = "删除指定子任务。\n\n**权限**：需管理员登录且为看板成员。")
     @DeleteMapping("/subtask/{subtaskId}")
     public Result<Void> deleteSubtask(@ApiParam("子任务ID") @PathVariable Long subtaskId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -148,7 +152,7 @@ public class TaskController {
 
     // ======================= Timeline (comments + activities) =======================
 
-    @ApiOperation("获取任务时间线")
+    @ApiOperation(value = "获取任务时间线", notes = "返回任务的完整操作记录，包含评论和系统自动记录的状态变更、人员分配等活动，按时间正序排列")
     @GetMapping("/{taskId}/timeline")
     public Result<List<TimelineItemVO>> getTimeline(@ApiParam("任务ID") @PathVariable Long taskId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -156,7 +160,7 @@ public class TaskController {
         return Result.success(commentService.getTimeline(taskId, adminId, role));
     }
 
-    @ApiOperation("添加评论")
+    @ApiOperation(value = "添加评论", notes = "在任务时间线中添加评论，添加后自动通知任务负责人")
     @PostMapping("/{taskId}/comment")
     public Result<TimelineItemVO> addComment(@ApiParam("任务ID") @PathVariable Long taskId,
                                               @ApiParam("创建评论请求") @Valid @RequestBody CreateCommentRequest req,
@@ -168,7 +172,7 @@ public class TaskController {
         return Result.success(item);
     }
 
-    @ApiOperation("删除评论")
+    @ApiOperation(value = "删除评论", notes = "仅评论作者本人可删除自己的评论，系统自动生成的活动记录不可删除")
     @DeleteMapping("/comment/{commentId}")
     public Result<Void> deleteComment(@ApiParam("评论ID") @PathVariable Long commentId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java
index 10fe201..c012fce 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java
@@ -22,7 +22,9 @@ public class AdminAgreementController {
 
     private final AgreementService agreementService;
 
-    @ApiOperation("协议列表")
+    @ApiOperation(value = "协议列表", notes = "分页查询用户协议列表，支持按关键词和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）")
     @GetMapping
     public Result<PageResult<AgreementVO>> listAgreements(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -32,20 +34,30 @@ public class AdminAgreementController {
         return Result.success(agreementService.listAgreements(page, pageSize, keyword, status));
     }
 
-    @ApiOperation("协议详情")
+    @ApiOperation(value = "协议详情",
+            notes = "获取指定用户协议的详细信息，包括标题、内容（富文本）、版本号等。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- common_status（通用状态）：返回字段status（0=禁用, 1=启用）")
     @GetMapping("/{id}")
     public Result<AgreementVO> getAgreement(@ApiParam("协议ID") @PathVariable Long id) {
         return Result.success(agreementService.getAgreement(id));
     }
 
-    @ApiOperation("新增协议")
+    @ApiOperation(value = "新增协议",
+            notes = "创建新的用户协议，如用户服务协议、隐私政策等。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：协议类型（type）需唯一，同一类型不能重复创建。内容支持富文本。")
     @OperationLog(value = "新增协议", module = "用户协议管理")
     @PostMapping
     public Result<AgreementVO> createAgreement(@Valid @RequestBody AgreementRequest request) {
         return Result.success(agreementService.createAgreement(request));
     }
 
-    @ApiOperation("编辑协议")
+    @ApiOperation(value = "编辑协议",
+            notes = "更新指定用户协议的标题、内容、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：修改后小程序端会实时展示新内容。")
     @OperationLog(value = "编辑协议", module = "用户协议管理")
     @PutMapping("/{id}")
     public Result<AgreementVO> updateAgreement(@ApiParam("协议ID") @PathVariable Long id,
@@ -53,7 +65,10 @@ public class AdminAgreementController {
         return Result.success(agreementService.updateAgreement(id, request));
     }
 
-    @ApiOperation("删除协议")
+    @ApiOperation(value = "删除协议",
+            notes = "删除指定的用户协议记录（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序端将无法查看该协议。")
     @OperationLog(value = "删除协议", module = "用户协议管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteAgreement(@ApiParam("协议ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java
index 5c47fa0..eec06ab 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java
@@ -23,7 +23,9 @@ public class AdminBannerController {
 
     private final BannerService bannerService;
 
-    @ApiOperation("Banner列表")
+    @ApiOperation(value = "Banner列表", notes = "分页查询Banner列表，支持按关键词和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）")
     @GetMapping
     public Result<PageResult<BannerVO>> listBanners(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -34,13 +36,20 @@ public class AdminBannerController {
         return Result.success(result);
     }
 
-    @ApiOperation("Banner详情")
+    @ApiOperation(value = "Banner详情",
+            notes = "获取指定Banner的详细信息，包括标题、图片、跳转链接、排序等。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- common_status（通用状态）：返回字段status（0=禁用, 1=启用）")
     @GetMapping("/{id}")
     public Result<BannerVO> getBanner(@ApiParam("轮播图ID") @PathVariable Long id) {
         return Result.success(bannerService.getBanner(id));
     }
 
-    @ApiOperation("创建Banner")
+    @ApiOperation(value = "创建Banner",
+            notes = "创建新的首页轮播图，包括标题、封面图、跳转链接、排序等。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：创建后默认为启用状态，小程序端将按排序展示。")
     @OperationLog(value = "创建Banner", module = "Banner管理")
     @PostMapping
     public Result<BannerVO> createBanner(@ApiParam("轮播图创建请求") @Valid @RequestBody BannerRequest request,
@@ -49,7 +58,9 @@ public class AdminBannerController {
         return Result.success(bannerService.createBanner(request, adminId));
     }
 
-    @ApiOperation("更新Banner")
+    @ApiOperation(value = "更新Banner",
+            notes = "更新指定Banner的标题、封面图、跳转链接、排序、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "更新Banner", module = "Banner管理")
     @PutMapping("/{id}")
     public Result<BannerVO> updateBanner(@ApiParam("轮播图ID") @PathVariable Long id,
@@ -57,7 +68,10 @@ public class AdminBannerController {
         return Result.success(bannerService.updateBanner(id, request));
     }
 
-    @ApiOperation("删除Banner")
+    @ApiOperation(value = "删除Banner",
+            notes = "删除指定的Banner记录（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序首页将不再展示该Banner。")
     @OperationLog(value = "删除Banner", module = "Banner管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteBanner(@ApiParam("轮播图ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java
index 6080439..786b6ad 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java
@@ -22,7 +22,10 @@ public class AdminContactController {
 
     private final ContactService contactService;
 
-    @ApiOperation("联系方式列表")
+    @ApiOperation(value = "联系方式列表", notes = "分页查询联系方式列表，支持按关键词和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- contact_channel_type（联系渠道类型）：返回字段channelType（PHONE=电话, WECHAT=微信, EMAIL=邮箱等）\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status")
     @GetMapping
     public Result<PageResult<ContactVO>> listContacts(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -33,20 +36,27 @@ public class AdminContactController {
         return Result.success(result);
     }
 
-    @ApiOperation("联系方式详情")
+    @ApiOperation(value = "联系方式详情", notes = "获取指定联系方式的详细信息。"
+            + "\n\n**关联字典**：\n"
+            + "- contact_channel_type（联系渠道类型）：返回字段channelType\n"
+            + "- common_status（通用状态）：返回字段status")
     @GetMapping("/{id}")
     public Result<ContactVO> getContact(@ApiParam("联系方式ID") @PathVariable Long id) {
         return Result.success(contactService.getContact(id));
     }
 
-    @ApiOperation("创建联系方式")
+    @ApiOperation(value = "创建联系方式", notes = "新增一条联系方式记录。"
+            + "\n\n**关联字典**：\n"
+            + "- contact_channel_type（联系渠道类型）：请求字段channelType")
     @OperationLog(value = "创建联系方式", module = "联系我们管理")
     @PostMapping
     public Result<ContactVO> createContact(@ApiParam("联系方式创建请求") @Valid @RequestBody ContactRequest request) {
         return Result.success(contactService.createContact(request));
     }
 
-    @ApiOperation("更新联系方式")
+    @ApiOperation(value = "更新联系方式", notes = "更新指定联系方式记录。"
+            + "\n\n**关联字典**：\n"
+            + "- contact_channel_type（联系渠道类型）：请求字段channelType")
     @OperationLog(value = "更新联系方式", module = "联系我们管理")
     @PutMapping("/{id}")
     public Result<ContactVO> updateContact(@ApiParam("联系方式ID") @PathVariable Long id,
@@ -54,7 +64,10 @@ public class AdminContactController {
         return Result.success(contactService.updateContact(id, request));
     }
 
-    @ApiOperation("删除联系方式")
+    @ApiOperation(value = "删除联系方式",
+            notes = "删除指定的联系方式记录（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序端将不再展示该联系方式。")
     @OperationLog(value = "删除联系方式", module = "联系我们管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteContact(@ApiParam("联系方式ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java
index 23ad20d..b5b5983 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java
@@ -19,7 +19,14 @@ public class AdminCustomerController {
 
     private final UserService userService;
 
-    @ApiOperation("客户列表")
+    @ApiOperation(value = "客户列表", notes = "分页查询小程序注册的C端用户（客户）列表。"
+            + "支持按昵称/手机号/真实姓名关键词搜索，按状态筛选。"
+            + "status取值：ACTIVE=正常 BANNED=已封禁。"
+            + "需要管理员认证。"
+            + "\n\n**关联字典**：\n"
+            + "- user_status（用户状态）：请求参数status和返回字段status（ACTIVE=正常, BANNED=已封禁）\n"
+            + "- gender（性别）：返回字段gender（0=女, 1=男）\n"
+            + "- id_card_type（证件类型）：返回字段idCardType")
     @GetMapping
     public Result<PageResult<CustomerVO>> listCustomers(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -30,14 +37,21 @@ public class AdminCustomerController {
         return Result.success(result);
     }
 
-    @ApiOperation("客户详情")
+    @ApiOperation(value = "客户详情", notes = "获取指定客户的详细信息。"
+            + "\n\n**关联字典**：\n"
+            + "- user_status（用户状态）：返回字段status\n"
+            + "- gender（性别）：返回字段gender\n"
+            + "- id_card_type（证件类型）：返回字段idCardType")
     @GetMapping("/{userId}")
     public Result<CustomerVO> getCustomer(@ApiParam("用户ID") @PathVariable Long userId) {
         CustomerVO customer = userService.getCustomerDetail(userId);
         return Result.success(customer);
     }
 
-    @ApiOperation("封禁客户")
+    @ApiOperation(value = "封禁客户", notes = "封禁指定的C端用户，状态变为BANNED。"
+            + "封禁后该用户无法登录小程序，已有的Token将失效。"
+            + "封禁操作不会删除用户数据，可通过[解封客户]接口恢复。"
+            + "需要管理员认证。")
     @OperationLog(value = "封禁客户", module = "客户管理")
     @PostMapping("/{userId}/ban")
     public Result<Void> banCustomer(@ApiParam("用户ID") @PathVariable Long userId) {
@@ -45,7 +59,9 @@ public class AdminCustomerController {
         return Result.success();
     }
 
-    @ApiOperation("解封客户")
+    @ApiOperation(value = "解封客户", notes = "解封已封禁的C端用户，状态恢复为ACTIVE。"
+            + "解封后用户可正常登录小程序。"
+            + "需要管理员认证。")
     @OperationLog(value = "解封客户", module = "客户管理")
     @PostMapping("/{userId}/unban")
     public Result<Void> unbanCustomer(@ApiParam("用户ID") @PathVariable Long userId) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java
index 5dfa05d..c76c659 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java
@@ -30,14 +30,18 @@ public class AdminDesignerController {
     private final DesignerProfileService designerProfileService;
     private final DesignerDashboardService designerDashboardService;
 
-    @ApiOperation("获取我的个人资料（已废弃，请使用 /admin/profile/me）")
+    @ApiOperation(value = "获取我的个人资料（已废弃，请使用 /admin/profile/me）", notes = "已废弃接口。"
+            + "\n\n**关联字典**：\n"
+            + "- designer_cert_level（认证等级）：返回字段certLevel（none/bronze/silver/gold/diamond）")
     @GetMapping("/profile")
     public Result<DesignerProfileVO> getMyProfile(HttpServletRequest request) {
         Long adminId = getAdminId(request);
         return Result.success(designerProfileService.getMyProfile(adminId));
     }
 
-    @ApiOperation("更新我的个人资料（已废弃，请使用 PUT /admin/profile/me）")
+    @ApiOperation(value = "更新我的个人资料（已废弃，请使用 PUT /admin/profile/me）",
+            notes = "已废弃接口，请迁移至 PUT /admin/profile/me。\n\n"
+                + "**权限**：需要管理员登录。")
     @PutMapping("/profile")
     public Result<DesignerProfileVO> updateMyProfile(HttpServletRequest request,
                                                       @Valid @RequestBody UpdateDesignerProfileRequest body) {
@@ -45,14 +49,18 @@ public class AdminDesignerController {
         return Result.success(designerProfileService.updateMyProfile(adminId, body));
     }
 
-    @ApiOperation("工作台概览（已废弃，请使用 /admin/profile/dashboard）")
+    @ApiOperation(value = "工作台概览（已废弃，请使用 /admin/profile/dashboard）",
+            notes = "已废弃接口，请迁移至 GET /admin/profile/dashboard。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/dashboard")
     public Result<DesignerDashboardVO> getDashboard(HttpServletRequest request) {
         Long adminId = getAdminId(request);
         return Result.success(designerDashboardService.getDashboard(adminId, "today"));
     }
 
-    @ApiOperation("我的订单列表（已废弃，请使用 /admin/profile/orders）")
+    @ApiOperation(value = "我的订单列表（已废弃，请使用 /admin/profile/orders）", notes = "已废弃接口。"
+            + "\n\n**关联字典**：\n"
+            + "- order_status（订单状态）：请求参数status和返回字段status")
     @GetMapping("/orders")
     public Result<PageResult<Map<String, Object>>> getMyOrders(
             HttpServletRequest request,
@@ -64,7 +72,9 @@ public class AdminDesignerController {
         return Result.success(designerDashboardService.getMyOrders(adminId, page, pageSize, status, keyword));
     }
 
-    @ApiOperation("我的产品列表（已废弃，请使用 /admin/profile/products）")
+    @ApiOperation(value = "我的产品列表（已废弃，请使用 /admin/profile/products）", notes = "已废弃接口。"
+            + "\n\n**关联字典**：\n"
+            + "- product_status（产品状态）：请求参数status和返回字段status")
     @GetMapping("/products")
     public Result<PageResult<Map<String, Object>>> getMyProducts(
             HttpServletRequest request,

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java
index ebe2d88..f6fe95a 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java
@@ -24,7 +24,9 @@ public class AdminExploreCategoryController {
 
     private final ExploreCategoryService exploreCategoryService;
 
-    @ApiOperation("探索分类列表")
+    @ApiOperation(value = "探索分类列表", notes = "分页查询探索分类列表，支持按关键词和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）")
     @GetMapping
     public Result<PageResult<ExploreCategoryVO>> listCategories(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -35,13 +37,20 @@ public class AdminExploreCategoryController {
         return Result.success(result);
     }
 
-    @ApiOperation("探索分类详情")
+    @ApiOperation(value = "探索分类详情",
+            notes = "获取指定探索分类的详细信息，包括标题、封面图、描述、关联的景区资源列表等。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- common_status（通用状态）：返回字段status（0=禁用, 1=启用）")
     @GetMapping("/{id}")
     public Result<ExploreCategoryDetailVO> getCategory(@ApiParam("分类ID") @PathVariable Long id) {
         return Result.success(exploreCategoryService.getCategory(id));
     }
 
-    @ApiOperation("创建探索分类")
+    @ApiOperation(value = "创建探索分类",
+            notes = "创建新的探索分类，用于小程序探索页面的分类展示。\n"
+                + "可关联多个景区资源，设置封面图和描述文字。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "创建探索分类", module = "探索管理")
     @PostMapping
     public Result<Void> createCategory(@ApiParam("分类创建请求") @Valid @RequestBody ExploreCategoryRequest request,
@@ -51,7 +60,9 @@ public class AdminExploreCategoryController {
         return Result.success();
     }
 
-    @ApiOperation("更新探索分类")
+    @ApiOperation(value = "更新探索分类",
+            notes = "更新指定探索分类的标题、封面图、描述、关联资源、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "更新探索分类", module = "探索管理")
     @PutMapping("/{id}")
     public Result<Void> updateCategory(@ApiParam("分类ID") @PathVariable Long id,
@@ -60,7 +71,10 @@ public class AdminExploreCategoryController {
         return Result.success();
     }
 
-    @ApiOperation("删除探索分类")
+    @ApiOperation(value = "删除探索分类",
+            notes = "删除指定的探索分类（软删除），同时清除关联的资源绑定关系。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序探索页面将不再展示该分类。")
     @OperationLog(value = "删除探索分类", module = "探索管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteCategory(@ApiParam("分类ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java
index 61a2dbb..11e1fdd 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java
@@ -26,20 +26,28 @@ public class AdminFaqController {
 
     // ==================== 分类 ====================
 
-    @ApiOperation("分类列表")
+    @ApiOperation(value = "分类列表",
+            notes = "获取所有FAQ分类的完整列表（不分页）。\n"
+                + "每个分类包含名称、排序号、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/categories")
     public Result<List<FaqCategoryVO>> listCategories() {
         return Result.success(faqService.listCategories());
     }
 
-    @ApiOperation("创建分类")
+    @ApiOperation(value = "创建分类",
+            notes = "创建新的FAQ分类，用于对常见问题进行归类。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：分类名称不能重复。")
     @OperationLog(value = "创建FAQ分类", module = "常见问题管理")
     @PostMapping("/categories")
     public Result<FaqCategoryVO> createCategory(@Valid @RequestBody FaqCategoryRequest request) {
         return Result.success(faqService.createCategory(request));
     }
 
-    @ApiOperation("更新分类")
+    @ApiOperation(value = "更新分类",
+            notes = "更新指定FAQ分类的名称、排序号、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "更新FAQ分类", module = "常见问题管理")
     @PutMapping("/categories/{id}")
     public Result<FaqCategoryVO> updateCategory(@ApiParam("分类ID") @PathVariable Long id,
@@ -47,7 +55,10 @@ public class AdminFaqController {
         return Result.success(faqService.updateCategory(id, request));
     }
 
-    @ApiOperation("删除分类")
+    @ApiOperation(value = "删除分类",
+            notes = "删除指定的FAQ分类（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除分类不会删除其下的条目，但条目将变为无分类状态。")
     @OperationLog(value = "删除FAQ分类", module = "常见问题管理")
     @DeleteMapping("/categories/{id}")
     public Result<Void> deleteCategory(@ApiParam("分类ID") @PathVariable Long id) {
@@ -57,21 +68,29 @@ public class AdminFaqController {
 
     // ==================== 条目 ====================
 
-    @ApiOperation("条目列表")
+    @ApiOperation(value = "条目列表",
+            notes = "查询FAQ条目列表，支持按分类ID筛选。\n"
+                + "返回问题标题、回答内容（富文本）、排序号等。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/items")
     public Result<List<FaqItemVO>> listItems(
             @ApiParam("分类ID（可选）") @RequestParam(required = false) Long categoryId) {
         return Result.success(faqService.listItems(categoryId));
     }
 
-    @ApiOperation("创建条目")
+    @ApiOperation(value = "创建条目",
+            notes = "创建一条常见问题，包含问题标题和回答（支持富文本）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：需指定所属分类ID，排序号越小越靠前。")
     @OperationLog(value = "创建FAQ条目", module = "常见问题管理")
     @PostMapping("/items")
     public Result<FaqItemVO> createItem(@Valid @RequestBody FaqItemRequest request) {
         return Result.success(faqService.createItem(request));
     }
 
-    @ApiOperation("更新条目")
+    @ApiOperation(value = "更新条目",
+            notes = "更新指定FAQ条目的问题标题、回答内容、排序号等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "更新FAQ条目", module = "常见问题管理")
     @PutMapping("/items/{id}")
     public Result<FaqItemVO> updateItem(@ApiParam("条目ID") @PathVariable Long id,
@@ -79,7 +98,10 @@ public class AdminFaqController {
         return Result.success(faqService.updateItem(id, request));
     }
 
-    @ApiOperation("删除条目")
+    @ApiOperation(value = "删除条目",
+            notes = "删除指定的FAQ条目（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序FAQ页面将不再展示该条目。")
     @OperationLog(value = "删除FAQ条目", module = "常见问题管理")
     @DeleteMapping("/items/{id}")
     public Result<Void> deleteItem(@ApiParam("条目ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java
index e81218e..5f5117b 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java
@@ -24,7 +24,9 @@ public class AdminFrontendConfigController {
 
     private final FrontendConfigService frontendConfigService;
 
-    @ApiOperation("配置列表")
+    @ApiOperation(value = "配置列表", notes = "分页查询前端配置列表，支持按关键词、分组和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）")
     @GetMapping
     public Result<PageResult<FrontendConfigVO>> listConfigs(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -35,7 +37,10 @@ public class AdminFrontendConfigController {
         return Result.success(frontendConfigService.listConfigs(page, pageSize, keyword, configGroup, status));
     }
 
-    @ApiOperation("配置列表（不分页）")
+    @ApiOperation(value = "配置列表（不分页）",
+            notes = "获取所有前端配置项的完整列表（不分页），支持按分组和状态筛选。\n"
+                + "适用于需要一次性加载全部配置的场景。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/all")
     public Result<List<FrontendConfigVO>> listAllConfigs(
             @ApiParam("配置分组") @RequestParam(required = false) String configGroup,
@@ -43,25 +48,37 @@ public class AdminFrontendConfigController {
         return Result.success(frontendConfigService.listAllConfigs(configGroup, status));
     }
 
-    @ApiOperation("配置详情")
+    @ApiOperation(value = "配置详情",
+            notes = "根据配置ID获取指定前端配置项的详细信息，包括key、value、分组、描述等。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/{id}")
     public Result<FrontendConfigVO> getConfig(@ApiParam("配置ID") @PathVariable Long id) {
         return Result.success(frontendConfigService.getConfig(id));
     }
 
-    @ApiOperation("按key查询配置")
+    @ApiOperation(value = "按key查询配置",
+            notes = "根据配置键（configKey）获取指定的前端配置项。\n"
+                + "configKey为全局唯一标识，如 app_name、primary_color 等。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/by-key/{key}")
     public Result<FrontendConfigVO> getConfigByKey(@ApiParam("配置键") @PathVariable String key) {
         return Result.success(frontendConfigService.getConfigByKey(key));
     }
 
-    @ApiOperation("获取所有分组")
+    @ApiOperation(value = "获取所有分组",
+            notes = "获取前端配置中所有已使用的分组名称列表。\n"
+                + "用于配置管理页面的分组筛选下拉框。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/groups")
     public Result<List<String>> listGroups() {
         return Result.success(frontendConfigService.listGroups());
     }
 
-    @ApiOperation("创建配置")
+    @ApiOperation(value = "创建配置",
+            notes = "创建新的前端配置项，用于控制前端页面的展示和行为。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：configKey 必须全局唯一，不能与已有配置重复。"
+                + "可通过 sensitive 字段标记是否为敏感配置（敏感配置不会通过公开接口暴露给小程序）。")
     @OperationLog(value = "创建前端配置", module = "前端配置管理")
     @PostMapping
     public Result<FrontendConfigVO> createConfig(
@@ -71,7 +88,10 @@ public class AdminFrontendConfigController {
         return Result.success(frontendConfigService.createConfig(request, adminId));
     }
 
-    @ApiOperation("更新配置")
+    @ApiOperation(value = "更新配置",
+            notes = "更新指定前端配置项的值、分组、描述、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：修改后前端会实时使用新值（如有缓存需等待刷新）。")
     @OperationLog(value = "更新前端配置", module = "前端配置管理")
     @PutMapping("/{id}")
     public Result<FrontendConfigVO> updateConfig(
@@ -80,7 +100,10 @@ public class AdminFrontendConfigController {
         return Result.success(frontendConfigService.updateConfig(id, request));
     }
 
-    @ApiOperation("删除配置")
+    @ApiOperation(value = "删除配置",
+            notes = "删除指定的前端配置项（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后前端将无法获取该配置，可能影响页面展示，请确认无引用后再删除。")
     @OperationLog(value = "删除前端配置", module = "前端配置管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteConfig(@ApiParam("配置ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java
index e174243..6558bc2 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java
@@ -29,7 +29,12 @@ public class AdminProfileController {
     private final FinanceDashboardService financeDashboardService;
     private final MaterialDashboardService materialDashboardService;
 
-    @ApiOperation("获取我的个人资料")
+    @ApiOperation(value = "获取我的个人资料",
+            notes = "获取当前登录管理员的个人资料，根据角色返回不同的资料内容。\n"
+                + "定制师角色会返回认证等级、个人简介、擅长领域等附加信息。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- designer_cert_level（认证等级）：返回字段certLevel（none/bronze/silver/gold/diamond）")
     @GetMapping("/me")
     public Result<ProfileVO> getMyProfile(HttpServletRequest request) {
         Long adminId = getAdminId(request);
@@ -37,7 +42,10 @@ public class AdminProfileController {
         return Result.success(profileService.getProfile(adminId, role));
     }
 
-    @ApiOperation("更新我的个人资料")
+    @ApiOperation(value = "更新我的个人资料",
+            notes = "更新当前登录管理员的个人资料，支持修改昵称、头像、个人简介等。\n"
+                + "定制师角色可额外更新擅长领域、服务区域等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @PutMapping("/me")
     public Result<ProfileVO> updateMyProfile(HttpServletRequest request,
                                               @Valid @RequestBody UpdateDesignerProfileRequest body) {
@@ -46,9 +54,19 @@ public class AdminProfileController {
         return Result.success(profileService.updateProfile(adminId, role, body));
     }
 
-    @ApiOperation("工作台仪表盘（角色分发，支持时间范围）")
+    @ApiOperation(value = "工作台仪表盘（角色分发，支持时间范围）", notes = "根据当前管理员角色返回不同的仪表盘数据。"
+            + "CUSTOMIZER（定制师）：待处理订单数、产品数、评价统计等。"
+            + "SUPER_ADMIN/ADMIN：全局概览（订单、收入、用户增长等）。"
+            + "ROOM_MANAGER（客房管理）：房间分配概览。"
+            + "VEHICLE_MANAGER（车辆管理）：车辆调度概览。"
+            + "FINANCE（财务）：收支统计。"
+            + "MATERIAL_ADMIN（素材管理）：素材库概览。"
+            + "period取值：today=今日 week=本周 month=本月。"
+            + "需要管理员认证。"
+            + "\n\n**关联字典**：\n"
+            + "- order_status（订单状态）：仪表盘中订单统计按状态分组展示")
     @GetMapping("/dashboard")
-    public Result<?> getDashboard(
+    public Result<Object> getDashboard(
             HttpServletRequest request,
             @ApiParam("时间范围: today/week/month") @RequestParam(defaultValue = "today") String period) {
         Long adminId = getAdminId(request);
@@ -72,7 +90,9 @@ public class AdminProfileController {
         }
     }
 
-    @ApiOperation("我的评价列表")
+    @ApiOperation(value = "我的评价列表", notes = "查询当前定制师收到的评价列表，支持按评价等级筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- rating_level（评价等级）：GOOD=好评, MEDIUM=中评, BAD=差评（筛选条件+列表展示）\n")
     @GetMapping("/reviews")
     public Result<PageResult<Map<String, Object>>> getReviews(
             HttpServletRequest request,
@@ -83,7 +103,9 @@ public class AdminProfileController {
         return Result.success(designerDashboardService.getMyReviews(adminId, page, pageSize, ratingLevel));
     }
 
-    @ApiOperation("订单列表")
+    @ApiOperation(value = "订单列表", notes = "查询当前定制师的订单列表，支持按状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- order_status（订单状态）：请求参数status和返回字段status")
     @GetMapping("/orders")
     public Result<PageResult<Map<String, Object>>> getOrders(
             HttpServletRequest request,
@@ -95,7 +117,9 @@ public class AdminProfileController {
         return Result.success(designerDashboardService.getMyOrders(adminId, page, pageSize, status, keyword));
     }
 
-    @ApiOperation("产品列表")
+    @ApiOperation(value = "产品列表", notes = "查询当前定制师的产品列表，支持按状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- product_status（产品状态）：请求参数status和返回字段status")
     @GetMapping("/products")
     public Result<PageResult<Map<String, Object>>> getProducts(
             HttpServletRequest request,

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java
index 7d2e9bc..e6766e3 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java
@@ -23,7 +23,9 @@ public class AdminTopicController {
 
     private final TopicService topicService;
 
-    @ApiOperation("专题列表")
+    @ApiOperation(value = "专题列表", notes = "分页查询探索专题列表，支持按关键词和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）")
     @GetMapping
     public Result<PageResult<TopicVO>> listTopics(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -34,13 +36,20 @@ public class AdminTopicController {
         return Result.success(result);
     }
 
-    @ApiOperation("专题详情")
+    @ApiOperation(value = "专题详情",
+            notes = "获取指定探索专题的详细信息，包括标题、封面图、描述、关联资源等。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- common_status（通用状态）：返回字段status（0=禁用, 1=启用）")
     @GetMapping("/{id}")
     public Result<TopicVO> getTopic(@ApiParam("专题ID") @PathVariable Long id) {
         return Result.success(topicService.getTopic(id));
     }
 
-    @ApiOperation("创建专题")
+    @ApiOperation(value = "创建专题",
+            notes = "创建新的探索专题，用于小程序探索页面展示主题推荐内容。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：创建时需设置标题、封面图等基本信息。")
     @OperationLog(value = "创建专题", module = "探索专题管理")
     @PostMapping
     public Result<TopicVO> createTopic(@ApiParam("专题创建请求") @Valid @RequestBody TopicRequest request,
@@ -49,7 +58,9 @@ public class AdminTopicController {
         return Result.success(topicService.createTopic(request, adminId));
     }
 
-    @ApiOperation("更新专题")
+    @ApiOperation(value = "更新专题",
+            notes = "更新指定探索专题的标题、封面图、描述、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "更新专题", module = "探索专题管理")
     @PutMapping("/{id}")
     public Result<TopicVO> updateTopic(@ApiParam("专题ID") @PathVariable Long id,
@@ -57,7 +68,10 @@ public class AdminTopicController {
         return Result.success(topicService.updateTopic(id, request));
     }
 
-    @ApiOperation("删除专题")
+    @ApiOperation(value = "删除专题",
+            notes = "删除指定的探索专题（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序探索页面将不再展示该专题。")
     @OperationLog(value = "删除专题", module = "探索专题管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteTopic(@ApiParam("专题ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java
index 2b3f74a..0344258 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java
@@ -26,7 +26,12 @@ public class AdminUserController {
 
     private final AdminUserService adminUserService;
 
-    @ApiOperation("创建管理员")
+    @ApiOperation(value = "创建管理员", notes = "创建新的后台管理员账号。"
+            + "默认密码为Admin@123456，管理员首次登录后建议修改密码。"
+            + "可通过roleIds分配多个角色，也兼容旧的单角色roleId参数。"
+            + "需要SUPER_ADMIN或ADMIN角色。"
+            + "\n\n**关联字典**：\n"
+            + "- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用\n")
     @OperationLog(value = "创建管理员", module = "管理员管理")
     @PostMapping
     public Result<AdminUser> createAdmin(@ApiParam("创建管理员请求") @Valid @RequestBody CreateAdminRequest request) {
@@ -34,7 +39,9 @@ public class AdminUserController {
         return Result.success(admin);
     }
 
-    @ApiOperation("更新管理员")
+    @ApiOperation(value = "更新管理员", notes = "更新管理员信息，包括用户名、状态、角色分配等。"
+            + "\n\n**关联字典**：\n"
+            + "- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用\n")
     @OperationLog(value = "更新管理员", module = "管理员管理")
     @PutMapping("/{adminId}")
     public Result<AdminUser> updateAdmin(@ApiParam("管理员ID") @PathVariable Long adminId,
@@ -43,7 +50,10 @@ public class AdminUserController {
         return Result.success(admin);
     }
 
-    @ApiOperation("删除管理员")
+    @ApiOperation(value = "删除管理员", notes = "删除指定管理员账号（软删除）。"
+            + "不能删除自己的账号，不能删除SUPER_ADMIN角色的账号（除非操作者也是SUPER_ADMIN）。"
+            + "删除后该管理员的登录状态自动失效。"
+            + "需要SUPER_ADMIN或ADMIN角色。")
     @OperationLog(value = "删除管理员", module = "管理员管理")
     @DeleteMapping("/{adminId}")
     public Result<Void> deleteAdmin(@ApiParam("管理员ID") @PathVariable Long adminId,
@@ -54,7 +64,9 @@ public class AdminUserController {
         return Result.success();
     }
 
-    @ApiOperation("解锁管理员")
+    @ApiOperation(value = "解锁管理员", notes = "解锁因登录失败次数过多而被锁定的管理员账号。"
+            + "管理员连续5次登录失败后账号自动锁定30分钟，此接口可立即解锁。"
+            + "需要SUPER_ADMIN或ADMIN角色。")
     @OperationLog(value = "解锁管理员", module = "管理员管理")
     @PostMapping("/{adminId}/unlock")
     public Result<Void> unlockAdmin(@ApiParam("管理员ID") @PathVariable Long adminId,
@@ -65,7 +77,10 @@ public class AdminUserController {
         return Result.success();
     }
 
-    @ApiOperation("重置密码")
+    @ApiOperation(value = "重置密码", notes = "将指定管理员的密码重置为默认密码（Admin@123456）。"
+            + "用于管理员忘记密码时由上级管理员操作重置。"
+            + "重置后管理员可用默认密码登录，建议立即修改。"
+            + "需要SUPER_ADMIN或ADMIN角色。")
     @OperationLog(value = "重置密码", module = "管理员管理")
     @PostMapping("/{adminId}/reset-password")
     public Result<Void> resetPassword(@ApiParam("管理员ID") @PathVariable Long adminId,
@@ -76,7 +91,10 @@ public class AdminUserController {
         return Result.success();
     }
 
-    @ApiOperation("修改企业微信绑定（支持换绑）")
+    @ApiOperation(value = "修改企业微信绑定（支持换绑）", notes = "为管理员绑定或更换企业微信账号。"
+            + "绑定后管理员可通过企业微信扫码登录，并可接收审批通知。"
+            + "如果目标企微ID已被其他管理员绑定，需设置forceRebind=true强制换绑。"
+            + "需要管理员认证。")
     @OperationLog(value = "修改企业微信绑定", module = "管理员管理")
     @PutMapping("/{adminId}/wechat-binding")
     public Result<Map<String, Object>> updateWechatBinding(
@@ -92,14 +110,21 @@ public class AdminUserController {
         return Result.success(result);
     }
 
-    @ApiOperation("获取管理员详情")
+    @ApiOperation(value = "获取管理员详情", notes = "获取指定管理员的完整信息。"
+            + "\n\n**关联字典**：\n"
+            + "- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用\n")
     @GetMapping("/{adminId}")
     public Result<AdminUser> getAdmin(@ApiParam("管理员ID") @PathVariable Long adminId) {
         AdminUser admin = adminUserService.getAdminById(adminId);
         return Result.success(admin);
     }
 
-    @ApiOperation("管理员列表")
+    @ApiOperation(value = "管理员列表", notes = "分页查询管理员列表，支持按角色、状态、企微绑定状态筛选。"
+            + "status取值：ACTIVE=正常 LOCKED=已锁定 DISABLED=已禁用。"
+            + "wechatBound：true=已绑定企业微信 false=未绑定。"
+            + "需要管理员认证。"
+            + "\n\n**关联字典**：\n"
+            + "- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用（筛选条件+列表展示）\n")
     @GetMapping
     public Result<PageResult<AdminUser>> listAdmins(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,

`hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java
index bf6beb1..84bf6c9 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java
@@ -30,7 +30,10 @@ public class AuthController {
     @Value("${auth.2fa-confirm-enabled:false}")
     private boolean twoFaConfirmEnabled;
 
-    @ApiOperation("管理员登录")
+    @ApiOperation(value = "管理员登录", notes = "管理员通过用户名+密码登录后台管理系统。"
+            + "首次在新设备登录时需要进行企业微信扫码二次验证（2FA），返回needTwoFa=true。"
+            + "登录失败5次后账号将被锁定30分钟。"
+            + "无需认证即可调用。")
     @PostMapping("/login")
     public Result<AdminLoginResponse> login(@ApiParam("管理员登录请求") @Valid @RequestBody AdminLoginRequest request,
                                               HttpServletRequest httpRequest) {
@@ -41,7 +44,10 @@ public class AuthController {
         return Result.success(response);
     }
 
-    @ApiOperation("2FA验证")
+    @ApiOperation(value = "2FA验证", notes = "新设备登录时的企业微信二次验证。"
+            + "管理员登录返回needTwoFa=true后，前端调用此接口提交验证码完成登录。"
+            + "验证通过后设备将被标记为可信设备，后续登录不再需要2FA。"
+            + "无需认证即可调用。")
     @PostMapping("/wechat/verify-2fa")
     public Result<AdminLoginResponse> verifyTwoFa(@ApiParam("管理员ID") @RequestParam Long adminId,
                                                     @ApiParam("2FA验证请求") @Valid @RequestBody TwoFaVerifyRequest request,
@@ -53,7 +59,10 @@ public class AuthController {
         return Result.success(response);
     }
 
-    @ApiOperation("修改密码")
+    @ApiOperation(value = "修改密码", notes = "管理员修改自己的登录密码。"
+            + "需验证旧密码正确后才能设置新密码，新密码须满足复杂度要求（8-128位，含大小写字母和数字）。"
+            + "修改成功后当前Token仍然有效，无需重新登录。"
+            + "需要管理员认证（Token中的adminId）。")
     @OperationLog(value = "修改密码", module = "认证管理")
     @PutMapping("/password")
     public Result<Void> changePassword(HttpServletRequest request,
@@ -63,7 +72,9 @@ public class AuthController {
         return Result.success();
     }
 
-    @ApiOperation("管理员登出")
+    @ApiOperation(value = "管理员登出", notes = "清除管理员的登录状态并使当前Token失效。"
+            + "前端应在登出后清除本地存储的Token和用户信息。"
+            + "需要管理员认证。")
     @PostMapping("/logout")
     public Result<Void> logout(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -71,14 +82,20 @@ public class AuthController {
         return Result.success();
     }
 
-    @ApiOperation("生成2FA扫码会话")
+    @ApiOperation(value = "生成2FA扫码会话", notes = "生成企业微信扫码二维码的会话信息，用于新设备二次验证。"
+            + "返回包含qrcodeUrl（二维码链接）和state（会话标识）。"
+            + "前端展示二维码后通过轮询 /2fa/check 接口检查扫码状态。"
+            + "无需认证即可调用（登录流程中使用）。")
     @GetMapping("/2fa/qrcode")
     public Result<Map<String, Object>> generate2FaQrcode(@ApiParam("管理员ID") @RequestParam Long adminId) {
         Map<String, Object> data = adminAuthService.generate2FaQrSession(adminId);
         return Result.success(data);
     }
 
-    @ApiOperation("2FA企微扫码回调")
+    @ApiOperation(value = "2FA企微扫码回调", notes = "企业微信OAuth回调地址，用户扫码授权后微信服务器回调此接口。"
+            + "此接口由微信服务器调用，非前端直接调用。"
+            + "回调成功后将state对应的会话标记为已扫码，前端轮询 /2fa/check 即可获取结果。"
+            + "返回HTML页面（成功/失败提示），不返回JSON。")
     @GetMapping(value = "/2fa/callback", produces = MediaType.TEXT_HTML_VALUE)
     @ResponseBody
     public String handle2FaCallback(@ApiParam("授权码") @RequestParam String code, @ApiParam("会话状态") @RequestParam String state) {
@@ -120,14 +137,19 @@ public class AuthController {
 
     // ==================== WeChat QR Direct Login ====================
 
-    @ApiOperation("生成企业微信扫码登录会话")
+    @ApiOperation(value = "生成企业微信扫码登录会话", notes = "生成企业微信扫码直接登录的会话信息（非2FA验证，而是扫码替代密码登录）。"
+            + "返回包含qrcodeUrl和state。前端展示二维码后通过轮询 /wechat-qr/status 检查登录状态。"
+            + "无需认证即可调用。")
     @GetMapping("/wechat-qr")
     public Result<Map<String, Object>> generateWechatLoginQr() {
         Map<String, Object> data = adminAuthService.generateWechatLoginQrSession();
         return Result.success(data);
     }
 
-    @ApiOperation("企业微信扫码登录回调")
+    @ApiOperation(value = "企业微信扫码登录回调", notes = "企业微信OAuth回调地址，扫码登录授权后微信服务器回调此接口。"
+            + "此接口由微信服务器调用，非前端直接调用。"
+            + "回调后标记会话为已扫码，前端通过轮询 /wechat-qr/status 获取登录结果。"
+            + "返回HTML页面，不返回JSON。")
     @GetMapping(value = "/wechat-qr/callback", produces = MediaType.TEXT_HTML_VALUE)
     @ResponseBody
     public String handleWechatLoginCallback(@ApiParam("授权码") @RequestParam String code, @ApiParam("会话状态") @RequestParam String state) {
@@ -167,7 +189,10 @@ public class AuthController {
         }
     }
 
-    @ApiOperation("查询企业微信扫码登录状态")
+    @ApiOperation(value = "查询企业微信扫码登录状态", notes = "前端轮询此接口检查扫码登录是否完成。"
+            + "返回status字段：PENDING=等待扫码，SCANNED=已扫码登录成功（附带token和用户信息）。"
+            + "建议轮询间隔2秒，超过5分钟未扫码会话自动失效。"
+            + "无需认证即可调用。")
     @GetMapping("/wechat-qr/status")
     public Result<Map<String, Object>> checkWechatLoginStatus(@ApiParam("会话状态") @RequestParam String state,
                                                                 HttpServletRequest httpRequest) {
@@ -178,7 +203,11 @@ public class AuthController {
         return Result.success(data);
     }
 
-    @ApiOperation("手动确认扫码（内网穿透环境workaround，默认关闭）")
+    @ApiOperation(value = "手动确认扫码（内网穿透环境workaround，默认关闭）",
+            notes = "在内网穿透环境下，企微回调可能无法正常到达，此接口作为手动替代方案。\n"
+                + "需在Nacos配置中开启 auth.2fa-confirm-enabled=true 才可使用。\n\n"
+                + "**权限**：无需认证（登录流程中使用）。\n"
+                + "**注意**：生产环境应保持关闭，仅限开发/测试时使用。")
     @PostMapping("/2fa/confirm")
     public Result<Void> confirm2FaScan(@ApiParam("会话状态") @RequestParam String state,
                                         @ApiParam("管理员ID") @RequestParam String adminId,
@@ -195,7 +224,10 @@ public class AuthController {
         return Result.success();
     }
 
-    @ApiOperation("查询2FA扫码状态")
+    @ApiOperation(value = "查询2FA扫码状态", notes = "前端轮询此接口检查2FA扫码验证是否完成。"
+            + "返回status字段：PENDING=等待扫码，SCANNED=已完成验证（附带token和用户信息）。"
+            + "建议轮询间隔2秒，超过5分钟未扫码会话自动失效。"
+            + "无需认证即可调用（登录流程中使用）。")
     @GetMapping("/2fa/check")
     public Result<Map<String, Object>> check2FaStatus(@ApiParam("会话状态") @RequestParam String state,
                                                        HttpServletRequest httpRequest) {
@@ -206,7 +238,10 @@ public class AuthController {
         return Result.success(data);
     }
 
-    @ApiOperation("切换当前角色")
+    @ApiOperation(value = "切换当前角色", notes = "多角色管理员切换当前活跃角色。"
+            + "切换后返回新的Token和角色对应的菜单权限，前端需更新本地Token并刷新菜单。"
+            + "只能切换到该管理员已分配的角色，否则报错。"
+            + "需要管理员认证。")
     @OperationLog(value = "切换角色", module = "认证管理")
     @PostMapping("/switch-role")
     public Result<AdminLoginResponse> switchRole(HttpServletRequest request,
@@ -216,7 +251,10 @@ public class AuthController {
         return Result.success(response);
     }
 
-    @ApiOperation("更新头像")
+    @ApiOperation(value = "更新头像", notes = "管理员更新自己的头像。"
+            + "需先通过文件服务上传图片获取OSS URL和fileId，再调用此接口绑定。"
+            + "旧头像的文件引用会自动解绑。"
+            + "需要管理员认证。")
     @OperationLog(value = "更新头像", module = "认证管理")
     @PutMapping("/avatar")
     public Result<Void> updateAvatar(HttpServletRequest request,
@@ -226,7 +264,9 @@ public class AuthController {
         return Result.success();
     }
 
-    @ApiOperation("获取当前管理员信息")
+    @ApiOperation(value = "获取当前管理员信息", notes = "获取当前登录管理员的完整信息，包括用户名、头像、角色列表、当前角色、菜单权限等。"
+            + "前端页面初始化时调用此接口获取用户信息和权限数据。"
+            + "需要管理员认证。")
     @GetMapping("/info")
     public Result<AdminLoginResponse> getAdminInfo(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");

`hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java
index 0b374f0..79a06b4 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java
@@ -22,7 +22,12 @@ public class FavoriteController {
 
     private final FavoriteService favoriteService;
 
-    @ApiOperation("添加收藏")
+    @ApiOperation(value = "添加收藏", notes = "将指定资源添加到当前用户的收藏列表。"
+            + "同一用户对同一资源不可重复收藏，重复收藏会报错。"
+            + "targetType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT/EXPLORE等。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索（请求参数targetType）\n")
     @PostMapping
     public Result<Favorite> addFavorite(HttpServletRequest request,
                                          @ApiParam("收藏请求") @Valid @RequestBody FavoriteRequest favoriteRequest) {
@@ -31,7 +36,11 @@ public class FavoriteController {
         return Result.success(favorite);
     }
 
-    @ApiOperation("收藏列表")
+    @ApiOperation(value = "收藏列表", notes = "分页查询当前用户的所有收藏记录，按收藏时间倒序排列。"
+            + "返回收藏记录的基础信息（不包含资源详情），需前端根据targetType和targetId再查详情。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：返回字段targetType，前端据此判断跳转到哪种资源详情页\n")
     @GetMapping
     public Result<PageResult<Favorite>> listFavorites(HttpServletRequest request,
                                                        @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -41,7 +50,9 @@ public class FavoriteController {
         return Result.success(result);
     }
 
-    @ApiOperation("删除收藏")
+    @ApiOperation(value = "删除收藏", notes = "根据收藏记录ID取消收藏。"
+            + "只能删除自己的收藏记录，删除他人的收藏会报权限错误。"
+            + "需要小程序用户认证。")
     @DeleteMapping("/{favoriteId}")
     public Result<Void> deleteFavorite(HttpServletRequest request,
                                         @ApiParam("收藏ID") @PathVariable Long favoriteId) {

`hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java
index 2616fdc..a24102e 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java
@@ -22,7 +22,13 @@ public class FootprintController {
 
     private final FootprintService footprintService;
 
-    @ApiOperation("添加足迹")
+    @ApiOperation(value = "添加足迹", notes = "记录用户浏览资源的足迹。"
+            + "同一用户对同一资源多次浏览只保留最新一条记录（更新时间）。"
+            + "resourceType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT等。"
+            + "通常由前端在进入资源详情页时自动调用。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- footprint_resource_type（足迹资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品（请求参数resourceType）\n")
     @PostMapping
     public Result<Footprint> addFootprint(HttpServletRequest request,
                                             @ApiParam("足迹请求") @Valid @RequestBody FootprintRequest footprintRequest) {
@@ -31,7 +37,10 @@ public class FootprintController {
         return Result.success(footprint);
     }
 
-    @ApiOperation("足迹列表")
+    @ApiOperation(value = "足迹列表", notes = "分页查询当前用户的浏览足迹，按浏览时间倒序排列。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- footprint_resource_type（足迹资源类型）：返回字段resourceType，前端据此判断跳转到哪种资源详情页\n")
     @GetMapping
     public Result<PageResult<Footprint>> listFootprints(HttpServletRequest request,
                                                           @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -41,7 +50,9 @@ public class FootprintController {
         return Result.success(result);
     }
 
-    @ApiOperation("删除足迹")
+    @ApiOperation(value = "删除足迹", notes = "根据足迹记录ID删除单条浏览足迹。"
+            + "只能删除自己的足迹记录。"
+            + "需要小程序用户认证。")
     @DeleteMapping("/{footprintId}")
     public Result<Void> deleteFootprint(HttpServletRequest request,
                                           @ApiParam("足迹ID") @PathVariable Long footprintId) {

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java
index 37a5069..bdd7f6d 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java
@@ -22,7 +22,7 @@ import java.util.*;
  * Called by other services via Feign (not exposed via gateway).
  */
 @Slf4j
-@Api(tags = "【内部接口】审批（Feign调用）")
+@Api(tags = "【内部接口】审批（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/wechat")
 @RequiredArgsConstructor
@@ -129,7 +129,11 @@ public class InternalApprovalController {
     @Value("${approval.product.control-ids.reason:}")
     private String controlIdProductReason;
 
-    @ApiOperation("Submit approval to enterprise WeChat OA")
+    @ApiOperation(value = "提交企业微信OA审批", notes = "内部接口，由其他服务通过Feign调用提交企微审批申请。"
+            + "根据templateId自动路由到对应的审批模板（资源上下架/产品上下架/退款申请/退款申诉）。"
+            + "需提供adminId（管理员提交）或wechatUserId（代理提交）。"
+            + "返回企微审批单号spNo，用于后续查询审批状态。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/submit-approval")
     public Result<ApprovalSubmitResultDTO> submitApproval(@RequestBody ApprovalSubmitDTO dto) {
         if (dto.getTemplateId() == null || dto.getTemplateId().isEmpty()) {
@@ -183,7 +187,10 @@ public class InternalApprovalController {
         return Result.success(result);
     }
 
-    @ApiOperation("Revoke a pending approval in enterprise WeChat OA")
+    @ApiOperation(value = "撤销企业微信OA审批", notes = "内部接口，撤销一个待审批的企微OA审批申请。"
+            + "仅PENDING状态的审批可以撤销，已审批的无法撤销。"
+            + "撤销失败不会抛异常（降级处理），业务侧需自行处理状态。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/revoke-approval/{spNo}")
     public Result<Void> revokeApproval(@PathVariable String spNo) {
         if (spNo == null || spNo.isEmpty()) {
@@ -200,7 +207,12 @@ public class InternalApprovalController {
         return Result.success();
     }
 
-    @ApiOperation("Get approval status from enterprise WeChat OA")
+    @ApiOperation(value = "查询企业微信OA审批状态", notes = "内部接口，根据审批单号查询企微审批的详细状态。"
+            + "返回审批状态（spStatus：1=审批中 2=已通过 3=已驳回 4=已撤销）、申请人、表单数据等。"
+            + "用于审批轮询兜底方案（ApprovalPollingService）。"
+            + "不经过Gateway，仅服务间调用。"
+            + "\n\n**关联字典**：\n"
+            + "- approval_sp_status（审批状态）：返回字段spStatus（1=审批中, 2=已通过, 3=已驳回, 4=已撤销）")
     @GetMapping("/approval-status/{spNo}")
     @SuppressWarnings("unchecked")
     public Result<Map<String, Object>> getApprovalStatus(@PathVariable String spNo) {

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java
index c2204f9..df482d7 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java
@@ -13,7 +13,7 @@ import java.util.Map;
  * 徽章内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/badge")
 @RequiredArgsConstructor
@@ -21,7 +21,10 @@ public class InternalBadgeController {
 
     private final BadgeService badgeService;
 
-    @ApiOperation("获取用户徽章数据")
+    @ApiOperation(value = "获取用户徽章数据",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取指定用户的各类未读数和待处理徽章数据（如未读消息数、待付款订单数等）。\n"
+                + "用于小程序个人中心页面的红点/数字徽章展示。")
     @GetMapping
     public Result<Map<String, Object>> getUserBadgeData(@RequestParam Long userId) {
         return Result.success(badgeService.getUserBadgeData(userId));

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java
index 4df5705..b339c1f 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java
@@ -16,7 +16,7 @@ import java.util.List;
  * Banner内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/banner")
 @RequiredArgsConstructor
@@ -24,7 +24,9 @@ public class InternalBannerController {
 
     private final BannerService bannerService;
 
-    @ApiOperation("获取当前有效Banner列表")
+    @ApiOperation(value = "获取当前有效Banner列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取所有状态为启用的Banner列表，按排序号排列，用于小程序首页轮播展示。")
     @GetMapping("/active")
     public Result<List<BannerVO>> listActiveBanners() {
         return Result.success(bannerService.listActiveBanners());

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java
index d38d4a3..dc412e7 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java
@@ -16,7 +16,7 @@ import java.util.List;
  * 联系我们内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/contact")
 @RequiredArgsConstructor
@@ -24,7 +24,10 @@ public class InternalContactController {
 
     private final ContactService contactService;
 
-    @ApiOperation("获取当前有效联系方式列表")
+    @ApiOperation(value = "获取当前有效联系方式列表", notes = "内部接口，获取所有状态为上线的联系方式。"
+            + "不经过Gateway，仅服务间调用。"
+            + "\n\n**关联字典**：\n"
+            + "- contact_channel_type（联系渠道类型）：返回字段channelType（ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询）\n")
     @GetMapping("/active")
     public Result<List<ContactVO>> listActiveContacts() {
         return Result.success(contactService.listActiveContacts());

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java
index 969a9d2..f96ec05 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java
@@ -14,7 +14,7 @@ import java.util.List;
  * C端定制师内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/designer")
 @RequiredArgsConstructor
@@ -22,20 +22,28 @@ public class InternalDesignerController {
 
     private final DesignerService designerService;
 
-    @ApiOperation("定制师列表")
+    @ApiOperation(value = "定制师列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "分页获取已上线的定制师列表，用于小程序定制师展示页面。\n"
+                + "返回定制师头像、昵称、认证等级、擅长领域等信息。")
     @GetMapping
     public Result<List<DesignerVO>> listDesigners(@RequestParam(defaultValue = "1") int page,
                                                    @RequestParam(defaultValue = "10") int limit) {
         return Result.success(designerService.listDesigners(page, limit));
     }
 
-    @ApiOperation("推荐定制师")
+    @ApiOperation(value = "推荐定制师",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取一位推荐定制师，用于小程序首页推荐位展示。\n"
+                + "推荐逻辑由后端按权重排序选取。")
     @GetMapping("/featured")
     public Result<DesignerVO> getFeaturedDesigner() {
         return Result.success(designerService.getFeaturedDesigner());
     }
 
-    @ApiOperation("定制师详情")
+    @ApiOperation(value = "定制师详情",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取指定定制师的详细信息，包括个人简介、擅长领域、服务案例等。")
     @GetMapping("/{id}")
     public Result<DesignerVO> getDesignerDetail(@PathVariable Long id) {
         return Result.success(designerService.getDesignerDetail(id));

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java
index 1e7bf8d..02ea651 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java
@@ -26,7 +26,7 @@ import java.util.stream.Collectors;
  * 探索分类内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "探索分类小程序接口")
+@Api(tags = "探索分类小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/explore")
 @RequiredArgsConstructor
@@ -38,7 +38,10 @@ public class InternalExploreCategoryController {
     private final FavoriteService favoriteService;
     private final UserLikeService userLikeService;
 
-    @ApiOperation("获取上线探索分类列表")
+    @ApiOperation(value = "获取上线探索分类列表", notes = "内部接口，获取已上线的探索分类列表，支持排序。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：仅返回status=1（启用）的分类\n"
+            + "- explore_sort_type（排序方式）：请求参数sortType（comprehensive=综合, newest=最新, hottest=最热）")
     @GetMapping("/active")
     public Result<PageResult<ExploreCategoryVO>> listActive(
             @ApiParam("排序方式：comprehensive=综合 newest=最新 hottest=最热") @RequestParam(defaultValue = "comprehensive") String sortType,
@@ -47,7 +50,10 @@ public class InternalExploreCategoryController {
         return Result.success(exploreCategoryService.listActive(sortType, page, pageSize));
     }
 
-    @ApiOperation("获取探索分类详情（自动增加浏览量）")
+    @ApiOperation(value = "获取探索分类详情（自动增加浏览量）",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取指定分类的详细信息，同时自动增加浏览量计数。\n"
+                + "如果传入 X-User-Id 请求头，还会返回当前用户的点赞和收藏状态。")
     @GetMapping("/{id}")
     public Result<ExploreCategoryDetailVO> getActiveDetail(
             @ApiParam("分类ID") @PathVariable Long id,
@@ -65,14 +71,19 @@ public class InternalExploreCategoryController {
         return Result.success(exploreCategoryService.getActiveDetail(id, isLiked, isFavorited));
     }
 
-    @ApiOperation("增加浏览量")
+    @ApiOperation(value = "增加浏览量",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "手动增加指定探索分类的浏览量计数（+1）。")
     @PostMapping("/{id}/view")
     public Result<Void> incrementViewCount(@ApiParam("分类ID") @PathVariable Long id) {
         exploreCategoryService.incrementViewCount(id);
         return Result.success();
     }
 
-    @ApiOperation("切换收藏状态")
+    @ApiOperation(value = "切换收藏状态",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "切换用户对指定探索分类的收藏状态：已收藏则取消，未收藏则添加。\n"
+                + "返回 true=已收藏，false=已取消收藏。同时更新分类的收藏计数。")
     @PostMapping("/{id}/favorite")
     public Result<Boolean> toggleFavorite(
             @ApiParam("分类ID") @PathVariable Long id,
@@ -101,7 +112,9 @@ public class InternalExploreCategoryController {
         }
     }
 
-    @ApiOperation("检查是否已收藏")
+    @ApiOperation(value = "检查是否已收藏",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "检查用户是否已收藏指定的探索分类，返回 true/false。")
     @GetMapping("/{id}/favorite/check")
     public Result<Boolean> checkFavorite(
             @ApiParam("分类ID") @PathVariable Long id,
@@ -109,7 +122,10 @@ public class InternalExploreCategoryController {
         return Result.success(favoriteService.checkFavorite(userId, TARGET_TYPE_EXPLORE, id));
     }
 
-    @ApiOperation("切换点赞状态")
+    @ApiOperation(value = "切换点赞状态",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "切换用户对指定探索分类的点赞状态：已点赞则取消，未点赞则添加。\n"
+                + "返回 true=已点赞，false=已取消。同时更新分类的点赞计数。")
     @PostMapping("/{id}/like")
     public Result<Boolean> toggleLike(
             @ApiParam("分类ID") @PathVariable Long id,
@@ -119,7 +135,9 @@ public class InternalExploreCategoryController {
         return Result.success(liked);
     }
 
-    @ApiOperation("检查是否已点赞")
+    @ApiOperation(value = "检查是否已点赞",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "检查用户是否已点赞指定的探索分类，返回 true/false。")
     @GetMapping("/{id}/like/check")
     public Result<Boolean> checkLike(
             @ApiParam("分类ID") @PathVariable Long id,
@@ -127,7 +145,10 @@ public class InternalExploreCategoryController {
         return Result.success(userLikeService.checkLike(userId, TARGET_TYPE_EXPLORE, id));
     }
 
-    @ApiOperation("获取同分类的景区资源列表")
+    @ApiOperation(value = "获取同分类的景区资源列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "根据景区ID查找与其同一探索分类下的其他景区资源，用于'相关推荐'展示。\n"
+                + "返回资源ID、名称、描述、封面图等基本信息。")
     @GetMapping("/related-scenic")
     public Result<List<Map<String, Object>>> getRelatedScenic(
             @ApiParam("景区ID") @RequestParam Long scenicId,

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java
index 90d24df..e00222c 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java
@@ -12,7 +12,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
-@Api(tags = "【内部接口】常见问题（Feign调用）")
+@Api(tags = "【内部接口】常见问题（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/faq")
 @RequiredArgsConstructor
@@ -20,7 +20,9 @@ public class InternalFaqController {
 
     private final FaqService faqService;
 
-    @ApiOperation("获取所有启用的FAQ（含分类和条目）")
+    @ApiOperation(value = "获取所有启用的FAQ（含分类和条目）",
+            notes = "内部服务间调用接口，由其他微服务通过 Feign 调用。\n"
+                + "获取所有状态为启用的FAQ分类及其下属条目，按排序号排列。")
     @GetMapping("/all")
     public Result<List<FaqCategoryVO>> getAllActiveFaq() {
         return Result.success(faqService.getAllActiveFaq());

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java
index 1f32c3b..4976f91 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java
@@ -14,7 +14,7 @@ import java.util.List;
  * 前端配置内部接口（仅供其他服务通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "【内部接口】前端配置（Feign调用）")
+@Api(tags = "【内部接口】前端配置（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/frontend-config")
 @RequiredArgsConstructor
@@ -22,32 +22,42 @@ public class InternalFrontendConfigController {
 
     private final FrontendConfigService frontendConfigService;
 
-    @ApiOperation("获取所有启用的前端配置")
+    @ApiOperation(value = "获取所有启用的前端配置",
+            notes = "内部服务间调用接口，由其他微服务通过 Feign 调用。\n"
+                + "获取所有状态为启用的前端配置项列表（含敏感配置）。")
     @GetMapping("/all")
     public Result<List<FrontendConfigVO>> listAllActiveConfigs() {
         return Result.success(frontendConfigService.listAllActiveConfigs());
     }
 
-    @ApiOperation("按分组获取启用的配置")
+    @ApiOperation(value = "按分组获取启用的配置",
+            notes = "内部服务间调用接口，由其他微服务通过 Feign 调用。\n"
+                + "按配置分组名获取该分组下所有已启用的配置项。")
     @GetMapping("/group/{group}")
     public Result<List<FrontendConfigVO>> listActiveConfigsByGroup(@PathVariable String group) {
         return Result.success(frontendConfigService.listActiveConfigsByGroup(group));
     }
 
-    @ApiOperation("按key获取单个配置")
+    @ApiOperation(value = "按key获取单个配置",
+            notes = "内部服务间调用接口，由其他微服务通过 Feign 调用。\n"
+                + "根据 configKey 获取单个已启用的配置项，不存在则返回错误。")
     @GetMapping("/key/{key}")
     public Result<FrontendConfigVO> getActiveConfigByKey(@PathVariable String key) {
         FrontendConfigVO vo = frontendConfigService.getActiveConfigByKey(key);
         return vo != null ? Result.success(vo) : Result.error("配置项不存在");
     }
 
-    @ApiOperation("获取所有非敏感的前端配置（供小程序使用）")
+    @ApiOperation(value = "获取所有非敏感的前端配置（供小程序使用）",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取所有已启用且非敏感（sensitive=false）的配置项，安全地暴露给小程序C端。")
     @GetMapping("/public")
     public Result<List<FrontendConfigVO>> listPublicConfigs() {
         return Result.success(frontendConfigService.listPublicConfigs());
     }
 
-    @ApiOperation("按分组获取非敏感配置（供小程序使用）")
+    @ApiOperation(value = "按分组获取非敏感配置（供小程序使用）",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "按分组获取非敏感配置，过滤掉标记为敏感的配置项。")
     @GetMapping("/public/group/{group}")
     public Result<List<FrontendConfigVO>> listPublicConfigsByGroup(@PathVariable String group) {
         return Result.success(frontendConfigService.listPublicConfigsByGroup(group));

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java
index aba407f..a14b558 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java
@@ -14,7 +14,7 @@ import java.util.*;
  * 通用点赞内部接口（供 hl-mp-service BFF 通过 Feign 调用）
  * 支持任意资源类型：REVIEW, EXPLORE, GUIDE 等
  */
-@Api(tags = "【内部接口】通用点赞（Feign调用）")
+@Api(tags = "【内部接口】通用点赞（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/like")
 @RequiredArgsConstructor
@@ -22,7 +22,9 @@ public class InternalLikeController {
 
     private final UserLikeService userLikeService;
 
-    @ApiOperation("切换点赞状态（通用）")
+    @ApiOperation(value = "切换点赞状态（通用）", notes = "内部接口，切换用户对指定资源的点赞状态。"
+            + "\n\n**关联字典**：\n"
+            + "- like_target_type（点赞目标类型）：请求参数targetType（REVIEW=评价, EXPLORE=探索, GUIDE=攻略）")
     @PostMapping("/toggle")
     public Result<Map<String, Object>> toggleLike(
             @ApiParam("目标类型") @RequestParam String targetType,
@@ -36,7 +38,9 @@ public class InternalLikeController {
         return Result.success(data);
     }
 
-    @ApiOperation("检查是否已点赞（通用）")
+    @ApiOperation(value = "检查是否已点赞（通用）", notes = "内部接口，检查用户是否已点赞指定资源。"
+            + "\n\n**关联字典**：\n"
+            + "- like_target_type（点赞目标类型）：请求参数targetType（REVIEW=评价, EXPLORE=探索, GUIDE=攻略）")
     @GetMapping("/check")
     public Result<Boolean> checkLike(
             @ApiParam("目标类型") @RequestParam String targetType,
@@ -45,7 +49,9 @@ public class InternalLikeController {
         return Result.success(userLikeService.checkLike(userId, targetType, targetId));
     }
 
-    @ApiOperation("批量检查是否已点赞（接受字符串ID，避免JS大数精度丢失）")
+    @ApiOperation(value = "批量检查是否已点赞（接受字符串ID，避免JS大数精度丢失）", notes = "内部接口，批量检查用户是否已点赞指定资源列表。"
+            + "\n\n**关联字典**：\n"
+            + "- like_target_type（点赞目标类型）：请求参数targetType（REVIEW=评价, EXPLORE=探索, GUIDE=攻略）")
     @PostMapping("/batch-check")
     public Result<List<String>> batchCheckLiked(
             @ApiParam("目标类型") @RequestParam String targetType,

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java
index 124fb4f..179904b 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java
@@ -24,7 +24,7 @@ import java.util.stream.Collectors;
  * Internal endpoint for monitor-service to query login logs.
  * NOT exposed via gateway.
  */
-@Api(tags = "【内部接口】登录日志（Feign调用）")
+@Api(tags = "【内部接口】登录日志（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal")
 @RequiredArgsConstructor
@@ -35,7 +35,14 @@ public class InternalLoginLogController {
 
     private static final DateTimeFormatter FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
 
-    @ApiOperation("Query login logs")
+    @ApiOperation(value = "查询登录日志", notes = "内部接口，供hl-monitor-service通过Feign查询管理员登录日志。"
+            + "支持按管理员ID、登录状态、时间范围筛选。"
+            + "status取值：SUCCESS=登录成功 FAILED=登录失败。"
+            + "时间格式：yyyy-MM-dd HH:mm:ss。"
+            + "不经过Gateway，仅服务间调用。"
+            + "\n\n**关联字典**：\n"
+            + "- login_status（登录状态）：请求参数status和返回字段status（SUCCESS=成功, FAILED=失败）\n"
+            + "- login_method（登录方式）：返回字段loginMethod（PASSWORD=密码, WECHAT_QR=企微扫码, TWO_FA=二次验证）")
     @GetMapping("/login-logs")
     public Result<PageResult<LoginLogVO>> queryLoginLogs(
             @RequestParam(defaultValue = "1") int page,

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java
index a8f1de8..8e53118 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java
@@ -11,7 +11,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/common")
 @RequiredArgsConstructor
@@ -19,19 +19,26 @@ public class InternalMpCommonController {
 
     private final CommonService commonService;
 
-    @ApiOperation("应用配置")
+    @ApiOperation(value = "应用配置",
+            notes = "内部服务间调用接口，由 hl-mp-service 调用。\n"
+                + "获取小程序应用的基础配置信息，如版本号、客服电话等。")
     @GetMapping("/config")
     public Result<Map<String, Object>> getConfig() {
         return Result.success(commonService.getConfig());
     }
 
-    @ApiOperation("FAQ列表")
+    @ApiOperation(value = "FAQ列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 调用。\n"
+                + "获取所有启用的FAQ分类及其条目，用于小程序帮助中心页面展示。")
     @GetMapping("/faq")
     public Result<List<Map<String, Object>>> listFaq() {
         return Result.success(commonService.listFaq());
     }
 
-    @ApiOperation("提交反馈")
+    @ApiOperation(value = "提交反馈",
+            notes = "内部服务间调用接口，由 hl-mp-service 调用。\n"
+                + "提交用户反馈意见，包括反馈内容、联系方式等。\n"
+                + "需传入 userId 参数标识提交反馈的用户。")
     @PostMapping("/feedback")
     public Result<Void> submitFeedback(@RequestParam Long userId,
                                         @RequestBody UserFeedback feedback) {
@@ -39,13 +46,18 @@ public class InternalMpCommonController {
         return Result.success(null);
     }
 
-    @ApiOperation("获取协议文本")
+    @ApiOperation(value = "获取协议文本",
+            notes = "内部服务间调用接口，由 hl-mp-service 调用。\n"
+                + "根据协议类型（如 user_agreement、privacy_policy）获取协议的富文本内容。\n"
+                + "用于小程序协议详情页面展示。")
     @GetMapping("/agreement/{type}")
     public Result<Map<String, Object>> getAgreement(@PathVariable String type) {
         return Result.success(commonService.getAgreement(type));
     }
 
-    @ApiOperation("获取所有已上线协议列表")
+    @ApiOperation(value = "获取所有已上线协议列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 调用。\n"
+                + "获取所有状态为启用的协议列表，用于小程序注册/登录时展示需要同意的协议链接。")
     @GetMapping("/agreement/list")
     public Result<List<Map<String, Object>>> listActiveAgreements() {
         return Result.success(commonService.listActiveAgreements());

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java
index e634ded..6028ac3 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java
@@ -19,7 +19,7 @@ import java.util.stream.Collectors;
  * C端字典内部接口(仅供 hl-mp-service BFF 通过 Feign 调用)
  * 不经过认证拦截器(/internal/** 已排除)
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/dict")
 @RequiredArgsConstructor
@@ -27,7 +27,9 @@ public class InternalMpDictController {
 
     private final SysDictService sysDictService;
 
-    @ApiOperation("获取所有字典数据(C端小程序)")
+    @ApiOperation(value = "获取所有字典数据(C端小程序)", notes = "内部接口，供hl-mp-service通过Feign获取小程序可用的字典数据。"
+            + "返回格式：[{dictType, dictName, dataList}]，与管理端字典数据格式一致。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/all")
     public Result<List<Map<String, Object>>> getAllDict() {
         List<DictVO> dictList = sysDictService.getAllDictForMiniApp();
@@ -44,7 +46,8 @@ public class InternalMpDictController {
         return Result.success(result);
     }
 
-    @ApiOperation("按字典类型获取字典数据列表")
+    @ApiOperation(value = "按字典类型获取字典数据列表", notes = "内部接口，根据字典类型编码（如order_status）获取该类型下的所有字典数据项。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/type/{dictType}")
     public Result<List<SysDictData>> getDictDataByType(
             @ApiParam("字典类型编码") @PathVariable String dictType) {

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java
index 4921435..f32737c 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java
@@ -14,7 +14,7 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "小程序消息接口")
+@Api(tags = "小程序消息接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/message")
 @RequiredArgsConstructor
@@ -22,19 +22,32 @@ public class InternalMpMessageController {
 
     private final UserMessageService userMessageService;
 
-    @ApiOperation("消息分类列表（含未读数和最新消息预览）")
+    @ApiOperation(value = "消息分类列表（含未读数和最新消息预览）", notes = "获取用户的消息分类汇总信息。"
+            + "每个分类返回：分类名称、未读消息数、最新一条消息的标题和时间。"
+            + "用于消息中心首页展示各分类入口。"
+            + "内部接口，由hl-mp-service通过Feign调用。"
+            + "\n\n**关联字典**：\n"
+            + "- message_category（消息分类）：返回字段code（ORDER=订单消息, TRIP=行程消息, SYSTEM=系统消息, PROMO=营销消息）")
     @GetMapping("/categories")
     public Result<List<CategorySummaryVO>> getCategories(@RequestParam("userId") Long userId) {
         return Result.success(userMessageService.getCategorySummaries(userId));
     }
 
-    @ApiOperation("消息摘要（兼容旧接口）")
+    @ApiOperation(value = "消息摘要（兼容旧接口）",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "功能同 /categories 接口，保留用于向后兼容旧版本小程序。")
     @GetMapping("/summary")
     public Result<List<CategorySummaryVO>> getSummary(@RequestParam("userId") Long userId) {
         return Result.success(userMessageService.getCategorySummaries(userId));
     }
 
-    @ApiOperation("分类内消息列表（进入后自动标记已读）")
+    @ApiOperation(value = "分类内消息列表（进入后自动标记已读）", notes = "分页查询指定分类下的消息列表，按时间倒序排列。"
+            + "进入该分类后自动将该分类的所有消息标记为已读。"
+            + "categoryCode参数支持旧参数名category（向后兼容）。"
+            + "内部接口，由hl-mp-service通过Feign调用。"
+            + "\n\n**关联字典**：\n"
+            + "- message_category（消息分类）：请求参数categoryCode（ORDER=订单消息, TRIP=行程消息, SYSTEM=系统消息, PROMO=营销消息）\n"
+            + "- message_biz_type（关联业务类型）：返回字段bizType（ORDER=订单, REFUND=退款, CONTRACT=合同）")
     @GetMapping("/list")
     public Result<PageResult<UserMessageVO>> listMessages(
             @RequestParam("userId") Long userId,
@@ -47,7 +60,9 @@ public class InternalMpMessageController {
         return Result.success(userMessageService.listMessages(userId, code, page, pageSize));
     }
 
-    @ApiOperation("获取总未读数")
+    @ApiOperation(value = "获取总未读数", notes = "获取用户所有分类的未读消息总数。"
+            + "返回{count: N}格式，用于小程序Tab栏消息角标显示。"
+            + "内部接口，由hl-mp-service通过Feign调用。")
     @GetMapping("/unread-count")
     public Result<Map<String, Integer>> getUnreadCount(@RequestParam("userId") Long userId) {
         Map<String, Integer> result = new HashMap<>();
@@ -55,7 +70,10 @@ public class InternalMpMessageController {
         return Result.success(result);
     }
 
-    @ApiOperation("全部标记已读")
+    @ApiOperation(value = "全部标记已读", notes = "将消息标记为已读。"
+            + "如果传入categoryCode，则只标记该分类下的消息为已读。"
+            + "如果不传categoryCode，则标记所有消息为已读。"
+            + "内部接口，由hl-mp-service通过Feign调用。")
     @PutMapping("/read-all")
     public Result<Void> markAllRead(
             @RequestParam("userId") Long userId,
@@ -70,7 +88,9 @@ public class InternalMpMessageController {
         return Result.success(null);
     }
 
-    @ApiOperation("标记已读")
+    @ApiOperation(value = "标记已读",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "将单条消息标记为已读（兼容旧接口，实际已被分类级别标记替代）。")
     @PutMapping("/{id}/read")
     public Result<Void> markRead(
             @RequestParam("userId") Long userId,
@@ -79,7 +99,9 @@ public class InternalMpMessageController {
         return Result.success(null);
     }
 
-    @ApiOperation("删除消息")
+    @ApiOperation(value = "删除消息",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "删除指定的用户消息记录，删除后不可恢复。")
     @DeleteMapping("/{id}")
     public Result<Void> deleteMessage(
             @RequestParam("userId") Long userId,

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java
index 69c0674..67190a9 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java
@@ -22,7 +22,7 @@ import java.util.Map;
  * C端用户内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/user")
 @RequiredArgsConstructor
@@ -37,26 +37,37 @@ public class InternalMpUserController {
 
     // ==================== Auth ====================
 
-    @ApiOperation("发送短信验证码")
+    @ApiOperation(value = "发送短信验证码",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "向指定手机号发送6位数字短信验证码，有效期5分钟，60秒内不可重复发送。")
     @PostMapping("/sms/send")
     public Result<Void> sendSmsCode(@Valid @RequestBody SendSmsRequest request) {
         smsService.sendVerificationCode(request.getPhone());
         return Result.success();
     }
 
-    @ApiOperation("短信登录")
+    @ApiOperation(value = "短信登录",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "小程序用户通过手机号+短信验证码登录，首次登录自动注册。\n"
+                + "返回JWT Token和用户基本信息。")
     @PostMapping("/login/sms")
     public Result<LoginResponse> loginBySms(@Valid @RequestBody SmsLoginRequest request) {
         return Result.success(userService.loginBySms(request));
     }
 
-    @ApiOperation("微信登录")
+    @ApiOperation(value = "微信登录",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "小程序用户通过微信授权码（wx.login获取的code）登录，首次登录自动注册。\n"
+                + "返回JWT Token和用户基本信息，含 needProfile 字段标识是否需要补全资料。")
     @PostMapping("/login")
     public Result<LoginResponse> login(@Valid @RequestBody LoginRequest request) {
         return Result.success(userService.login(request));
     }
 
-    @ApiOperation("获取用户信息")
+    @ApiOperation(value = "获取用户信息", notes = "内部接口，获取用户个人资料，含真实手机号。"
+            + "\n\n**关联字典**：\n"
+            + "- gender（性别）：返回字段gender\n"
+            + "- id_card_type（证件类型）：返回字段idCardType")
     @GetMapping("/profile")
     public Result<UserVO> getProfile(@RequestParam Long userId) {
         UserVO vo = userService.getProfile(userId);
@@ -65,21 +76,31 @@ public class InternalMpUserController {
         return Result.success(vo);
     }
 
-    @ApiOperation("更新用户信息")
+    @ApiOperation(value = "更新用户信息",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "更新用户个人资料，包括昵称、头像、性别、实名信息等。\n"
+                + "首次补全资料时 realName/idCardType/idCardNo 为必填。\n\n"
+                + "**关联字典**：\n"
+                + "- gender（性别）：请求字段gender\n"
+                + "- id_card_type（证件类型）：请求字段idCardType")
     @PutMapping("/profile")
     public Result<UserVO> updateProfile(@RequestParam Long userId,
                                        @Valid @RequestBody UpdateProfileRequest request) {
         return Result.success(userService.updateProfile(userId, request));
     }
 
-    @ApiOperation("用户登出")
+    @ApiOperation(value = "用户登出",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "清除指定用户的登录状态，使Token失效。")
     @PostMapping("/logout")
     public Result<Void> logout(@RequestParam Long userId) {
         userService.logout(userId);
         return Result.success();
     }
 
-    @ApiOperation("注销账号")
+    @ApiOperation(value = "注销账号",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "永久注销用户账号（软删除），注销后该手机号可重新注册。")
     @DeleteMapping("/account")
     public Result<Void> deleteAccount(@RequestParam Long userId) {
         userService.deleteAccount(userId);
@@ -88,14 +109,18 @@ public class InternalMpUserController {
 
     // ==================== Favorite ====================
 
-    @ApiOperation("添加收藏")
+    @ApiOperation(value = "添加收藏", notes = "内部接口，为用户添加收藏。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：请求参数targetType（SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索）")
     @PostMapping("/favorite")
     public Result<Favorite> addFavorite(@RequestParam Long userId,
                                        @Valid @RequestBody FavoriteRequest request) {
         return Result.success(favoriteService.addFavorite(userId, request));
     }
 
-    @ApiOperation("收藏列表")
+    @ApiOperation(value = "收藏列表", notes = "内部接口，获取用户收藏列表。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：请求参数targetType和返回字段targetType（SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索）")
     @GetMapping("/favorite")
     public Result<PageResult<Favorite>> listFavorites(@RequestParam Long userId,
                                                      @RequestParam(required = false) String targetType,
@@ -104,7 +129,9 @@ public class InternalMpUserController {
         return Result.success(favoriteService.listFavorites(userId, targetType, page, pageSize));
     }
 
-    @ApiOperation("检查是否已收藏")
+    @ApiOperation(value = "检查是否已收藏", notes = "内部接口，检查用户是否已收藏指定资源。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：请求参数targetType")
     @GetMapping("/favorite/check")
     public Result<Boolean> checkFavorite(@RequestParam Long userId,
                                         @RequestParam String targetType,
@@ -112,7 +139,9 @@ public class InternalMpUserController {
         return Result.success(favoriteService.checkFavorite(userId, targetType, targetId));
     }
 
-    @ApiOperation("批量删除收藏")
+    @ApiOperation(value = "批量删除收藏",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "根据收藏记录ID列表批量删除用户的收藏记录。")
     @DeleteMapping("/favorite/batch")
     public Result<Void> batchDeleteFavorites(@RequestParam Long userId,
                                              @RequestBody List<Long> ids) {
@@ -120,7 +149,9 @@ public class InternalMpUserController {
         return Result.success();
     }
 
-    @ApiOperation("按目标取消收藏")
+    @ApiOperation(value = "按目标取消收藏", notes = "内部接口，按目标类型和ID取消收藏。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：请求参数targetType")
     @DeleteMapping("/favorite/by-target")
     public Result<Void> deleteFavoriteByTarget(@RequestParam Long userId,
                                                @RequestParam String targetType,
@@ -129,7 +160,9 @@ public class InternalMpUserController {
         return Result.success();
     }
 
-    @ApiOperation("取消收藏")
+    @ApiOperation(value = "取消收藏",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "根据收藏记录ID删除单条收藏记录。")
     @DeleteMapping("/favorite/{id}")
     public Result<Void> deleteFavorite(@RequestParam Long userId, @PathVariable Long id) {
         favoriteService.deleteFavorite(userId, id);
@@ -138,14 +171,18 @@ public class InternalMpUserController {
 
     // ==================== Footprint ====================
 
-    @ApiOperation("记录足迹")
+    @ApiOperation(value = "记录足迹", notes = "内部接口，记录用户浏览足迹。"
+            + "\n\n**关联字典**：\n"
+            + "- footprint_resource_type（足迹资源类型）：请求参数resourceType（SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品）")
     @PostMapping("/footprint")
     public Result<Footprint> addFootprint(@RequestParam Long userId,
                                          @Valid @RequestBody FootprintRequest request) {
         return Result.success(footprintService.addFootprint(userId, request));
     }
 
-    @ApiOperation("足迹列表")
+    @ApiOperation(value = "足迹列表", notes = "内部接口，获取用户足迹列表。"
+            + "\n\n**关联字典**：\n"
+            + "- footprint_resource_type（足迹资源类型）：请求参数resourceType和返回字段resourceType（SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品）")
     @GetMapping("/footprint")
     public Result<PageResult<Footprint>> listFootprints(@RequestParam Long userId,
                                                        @RequestParam(required = false) String resourceType,
@@ -154,7 +191,9 @@ public class InternalMpUserController {
         return Result.success(footprintService.listFootprints(userId, resourceType, page, pageSize));
     }
 
-    @ApiOperation("批量删除足迹")
+    @ApiOperation(value = "批量删除足迹",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "根据足迹记录ID列表批量删除用户的浏览足迹。")
     @DeleteMapping("/footprint/batch")
     public Result<Void> batchDeleteFootprints(@RequestParam Long userId,
                                               @RequestBody List<Long> ids) {
@@ -162,7 +201,9 @@ public class InternalMpUserController {
         return Result.success();
     }
 
-    @ApiOperation("删除足迹")
+    @ApiOperation(value = "删除足迹",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "根据足迹记录ID删除单条浏览足迹。")
     @DeleteMapping("/footprint/{id}")
     public Result<Void> deleteFootprint(@RequestParam Long userId, @PathVariable Long id) {
         footprintService.deleteFootprint(userId, id);
@@ -171,26 +212,45 @@ public class InternalMpUserController {

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java
index df5bc72..581cc22 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java
@@ -17,7 +17,7 @@ import java.util.Map;
 /**
  * Internal API for order service
  */
-@Api(tags = "【内部接口】订单用户（Feign调用）")
+@Api(tags = "【内部接口】订单用户（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/order/user")
 @RequiredArgsConstructor
@@ -25,7 +25,10 @@ public class InternalOrderUserController {
 
     private final UserService userService;
 
-    @ApiOperation("获取用户基本信息（供订单服务查询使用）")
+    @ApiOperation(value = "获取用户基本信息（供订单服务查询使用）",
+            notes = "内部服务间调用接口，由 hl-order-service 通过 Feign 调用。\n"
+                + "根据 userId 获取用户基本信息（userId、realName、phone），用于订单详情展示。\n"
+                + "**注意**：返回的手机号为真实手机号（未脱敏）。")
     @GetMapping("/info")
     public Result<Map<String, Object>> getUserInfo(@RequestParam Long userId) {
         User user = userService.getById(userId);

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java
index fba4363..e432e26 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java
@@ -16,7 +16,7 @@ import java.util.List;
  * 探索专题内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/topic")
 @RequiredArgsConstructor
@@ -24,7 +24,9 @@ public class InternalTopicController {
 
     private final TopicService topicService;
 
-    @ApiOperation("获取当前有效专题列表")
+    @ApiOperation(value = "获取当前有效专题列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取所有状态为启用的探索专题列表，按排序号排列，用于小程序探索页面展示。")
     @GetMapping("/active")
     public Result<List<TopicVO>> listActiveTopics() {
         return Result.success(topicService.listActiveTopics());

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java
index 6e38f29..d41fb78 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java
@@ -29,7 +29,7 @@ import java.util.*;
 import java.util.stream.Collectors;
 
 @Slf4j
-@Api(tags = "【内部接口】用户信息（Feign调用）")
+@Api(tags = "【内部接口】用户信息（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/user")
 @RequiredArgsConstructor
@@ -44,7 +44,8 @@ public class InternalUserController {
     private final WechatMiniAppClient wechatMiniAppClient;
     private final UserService userService;
 
-    @ApiOperation("Get admin basic info by ID")
+    @ApiOperation(value = "根据ID获取管理员基本信息", notes = "内部接口，供其他服务通过Feign查询管理员基础信息（ID、用户名、头像、企微姓名）。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/admin/info/{adminId}")
     public Result<AdminBasicDTO> getAdminInfo(@PathVariable Long adminId) {
         AdminUser admin = adminUserMapper.selectById(adminId);
@@ -55,7 +56,9 @@ public class InternalUserController {
         return Result.success(toBasicDTO(admin, wechatNameMap));
     }
 
-    @ApiOperation("Batch get admin basic info")
+    @ApiOperation(value = "批量获取管理员基本信息", notes = "内部接口，批量查询多个管理员的基础信息。"
+            + "传入adminId列表，返回对应的管理员信息列表。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/admin/batch-info")
     public Result<List<AdminBasicDTO>> batchGetAdminInfo(@RequestBody List<Long> adminIds) {
         if (adminIds == null || adminIds.isEmpty()) {
@@ -69,7 +72,9 @@ public class InternalUserController {
         return Result.success(result);
     }
 
-    @ApiOperation("Get all departments")
+    @ApiOperation(value = "获取所有部门列表", notes = "内部接口，获取企业微信同步的所有部门数据。"
+            + "用于通知规则配置等场景中的部门选择。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/departments")
     public Result<List<DepartmentDTO>> getDepartments() {
         List<WechatDepartment> depts = wechatDepartmentMapper.selectList(null);
@@ -85,7 +90,10 @@ public class InternalUserController {
         return Result.success(result);
     }
 
-    @ApiOperation("Get admin IDs belonging to a department")
+    @ApiOperation(value = "获取部门下的管理员ID列表", notes = "内部接口，查询指定部门下所有活跃管理员的ID。"
+            + "通过企微用户的部门归属关联到管理员账号。"
+            + "用于通知规则引擎按部门发送通知。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/admin/dept-members/{deptId}")
     public Result<List<Long>> getDeptAdminIds(@PathVariable Long deptId) {
         // Find wechat users in this department using FIND_IN_SET for exact match
@@ -113,7 +121,9 @@ public class InternalUserController {
         return Result.success(adminIds);
     }
 
-    @ApiOperation("Get admins by role key")
+    @ApiOperation(value = "根据角色标识获取管理员列表", notes = "内部接口，根据角色标识（如CUSTOMIZER、FINANCE等）查询该角色下所有活跃管理员。"
+            + "用于通知规则引擎按角色发送通知。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/admin/by-role-key")
     public Result<List<AdminBasicDTO>> getAdminsByRoleKey(@RequestParam String roleKey) {
         if (roleKey == null || roleKey.isBlank()) {
@@ -148,7 +158,10 @@ public class InternalUserController {
         return Result.success(result);
     }
 
-    @ApiOperation("Find C-end user ID by phone number")
+    @ApiOperation(value = "根据手机号查找C端用户ID", notes = "内部接口，根据手机号查找活跃的小程序用户。"
+            + "用于订单绑定流程中通过联系人手机号匹配用户。"
+            + "找不到时返回null（不报错）。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/find-by-phone")
     public Result<Long> findUserByPhone(@RequestParam String phone) {
         if (phone == null || phone.isBlank()) {
@@ -162,7 +175,9 @@ public class InternalUserController {
         return Result.success(user != null ? user.getUserId() : null);
     }
 
-    @ApiOperation("Generate mini program URL Link for sharing")
+    @ApiOperation(value = "生成小程序URL Link", notes = "内部接口，生成小程序短链接用于分享。"
+            + "通过微信API生成URL Link，可在浏览器/短信中打开小程序指定页面。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/wechat/miniapp/generate-url-link")
     public Result<Map<String, Object>> generateUrlLink(
             @RequestParam String path, @RequestParam String query) {
@@ -170,7 +185,10 @@ public class InternalUserController {
         return Result.success(result);
     }
 
-    @ApiOperation("Send WeChat message to users")
+    @ApiOperation(value = "发送企业微信消息", notes = "内部接口，向指定的企微用户发送文本消息。"
+            + "toUserIds为企微用户ID列表，支持一次发送给多人。"
+            + "用于审批通知、订单提醒等场景。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/wechat/send-message")
     public Result<Void> sendWechatMessage(@RequestBody WechatMessageDTO dto) {
         if (dto.getToUserIds() == null || dto.getToUserIds().isEmpty()) {

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java
index e0d5a6d..d192b76 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java
@@ -18,7 +18,7 @@ import org.springframework.web.bind.annotation.*;
  * No JWT auth required (excluded from TokenInterceptor via /internal/** pattern).
  */
 @Slf4j
-@Api(tags = "【内部接口】企微同步（Feign调用）")
+@Api(tags = "【内部接口】企微同步（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/wechat")
 @RequiredArgsConstructor
@@ -27,9 +27,11 @@ public class InternalWechatController {
     private final WechatSyncService wechatSyncService;
     private final ExternalContactNotifyService externalContactNotifyService;
 
-    @ApiOperation("Sync single user from callback")
+    @ApiOperation(value = "同步单个企微用户（回调触发）", notes = "内部接口，由hl-callback-service在收到企微通讯录变更回调时调用。"
+            + "将单个用户的信息同步到本地wechat_user表。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/user/sync")
-    public Result<?> syncUser(@RequestBody WechatUserSyncDTO dto) {
+    public Result<Void> syncUser(@RequestBody WechatUserSyncDTO dto) {
         log.info("Internal: sync user userid={}", dto.getUserid());
         try {
             wechatSyncService.syncSingleUserFromDto(dto);
@@ -40,9 +42,11 @@ public class InternalWechatController {
         }
     }
 
-    @ApiOperation("Delete single user from callback")
+    @ApiOperation(value = "删除单个企微用户（回调触发）", notes = "内部接口，由hl-callback-service在收到企微成员离职回调时调用。"
+            + "从本地wechat_user表中删除该用户记录。"
+            + "不经过Gateway，仅服务间调用。")
     @DeleteMapping("/user/{userid}")
-    public Result<?> deleteUser(@PathVariable("userid") String userid) {
+    public Result<Void> deleteUser(@PathVariable("userid") String userid) {
         log.info("Internal: delete user userid={}", userid);
         try {
             wechatSyncService.deleteSingleUser(userid);
@@ -53,9 +57,11 @@ public class InternalWechatController {
         }
     }
 
-    @ApiOperation("Sync single department from callback")
+    @ApiOperation(value = "同步单个企微部门（回调触发）", notes = "内部接口，由hl-callback-service在收到企微部门变更回调时调用。"
+            + "将单个部门的信息同步到本地wechat_department表。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/department/sync")
-    public Result<?> syncDepartment(@RequestBody WechatDeptSyncDTO dto) {
+    public Result<Void> syncDepartment(@RequestBody WechatDeptSyncDTO dto) {
         log.info("Internal: sync department deptId={}", dto.getId());
         try {
             wechatSyncService.syncSingleDepartmentFromDto(dto);
@@ -66,18 +72,22 @@ public class InternalWechatController {
         }
     }
 
-    @ApiOperation("Receive external contact change event")
+    @ApiOperation(value = "接收外部联系人变更事件", notes = "内部接口，由hl-callback-service在收到企微外部联系人变更回调时调用。"
+            + "处理客户添加/删除等事件，异步执行通知逻辑。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/external-contact/event")
-    public Result<?> handleExternalContactEvent(@RequestBody ExternalContactEventDTO dto) {
+    public Result<Void> handleExternalContactEvent(@RequestBody ExternalContactEventDTO dto) {
         log.info("Internal: external contact event changeType={}, userId={}, externalUserId={}",
                 dto.getChangeType(), dto.getUserId(), dto.getExternalUserId());
         externalContactNotifyService.processEventAsync(dto);
         return Result.success();
     }
 
-    @ApiOperation("Delete single department from callback")
+    @ApiOperation(value = "删除单个企微部门（回调触发）", notes = "内部接口，由hl-callback-service在收到企微部门删除回调时调用。"
+            + "从本地wechat_department表中删除该部门记录。"
+            + "不经过Gateway，仅服务间调用。")
     @DeleteMapping("/department/{deptId}")
-    public Result<?> deleteDepartment(@PathVariable("deptId") Long deptId) {
+    public Result<Void> deleteDepartment(@PathVariable("deptId") Long deptId) {
         log.info("Internal: delete department deptId={}", deptId);
         try {
             wechatSyncService.deleteSingleDepartment(deptId);

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java
index 44641ef..e3cf403 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java
@@ -15,7 +15,7 @@ import java.util.Map;
  * 祈愿内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/wish")
 @RequiredArgsConstructor
@@ -23,13 +23,17 @@ public class InternalWishController {
 
     private final WishService wishService;
 
-    @ApiOperation("获取用户祈愿列表")
+    @ApiOperation(value = "获取用户祈愿列表", notes = "内部接口，获取用户的祈愿列表。"
+            + "\n\n**关联字典**：\n"
+            + "- wish_type（心愿类型）：返回字段wishType（1=想去的地方, 2=想做的事, 3=其他）")
     @GetMapping
     public Result<List<WishVO>> listWishes(@RequestParam Long userId) {
         return Result.success(wishService.listWishes(userId));
     }
 
-    @ApiOperation("创建祈愿")
+    @ApiOperation(value = "创建祈愿", notes = "内部接口，创建用户祈愿。"
+            + "\n\n**关联字典**：\n"
+            + "- wish_type（心愿类型）：请求参数wishType（1=想去的地方, 2=想做的事, 3=其他）")
     @PostMapping
     public Result<WishVO> createWish(@RequestParam Long userId,
                                      @RequestBody Map<String, Object> request) {

`hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java
index 5acc247..753577c 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java
@@ -24,7 +24,7 @@ import java.util.Map;
 @RestController
 @RequestMapping("/oa/callback")
 @RequiredArgsConstructor
-@Api(tags = "【回调接口】公众号回调")
+@Api(tags = "【回调接口】公众号回调", hidden = true)
 public class OfficialAccountCallbackController {
 
     private final WechatOfficialAccountClient oaClient;

`hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java
index 6d1ec31..38f0ad6 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java
@@ -24,7 +24,12 @@ public class PublicDictController {
 
     private final SysDictService sysDictService;
 
-    @ApiOperation("获取所有字典数据")
+    @ApiOperation(value = "获取所有字典数据（公开接口）", notes = "获取系统全部字典类型及其字典数据，供小程序C端使用。"
+            + "无需认证即可调用。返回格式与管理端 /admin/dict/all 一致。"
+            + "\n\n**字典层级说明**：\n"
+            + "- 每个元素包含 dictType（编码）、dictName（名称）、dataList（字典数据列表）\n"
+            + "- 前端通过 dictType 匹配业务字段，用 dataList 中的 dictValue/dictLabel 做翻译展示\n"
+            + "- 常用字典：order_status、product_status、id_card_type、gender、traveler_type、favorite_resource_type、footprint_resource_type\n")
     @GetMapping("/all")
     public Result<List<DictVO>> getAllDict() {
         return Result.success(sysDictService.getAllDictForPublic());

`hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java
index 5be6ee7..260eadd 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java
@@ -26,7 +26,14 @@ public class SysDictController {
 
     // ======================== All Dict ========================
 
-    @ApiOperation("获取所有字典数据")
+    @ApiOperation(value = "获取所有字典数据", notes = "获取系统全部字典类型及其字典数据，按字典类型分组返回。"
+            + "用于后台管理系统初始化时一次性加载所有下拉选项。"
+            + "返回结果包含dictType编码、dictName名称、dataList数据列表。"
+            + "需要管理员认证。"
+            + "\n\n**字典层级说明**：\n"
+            + "- 字典类型（SysDictType）：一级分类，如 admin_status、order_status、id_card_type 等\n"
+            + "- 字典数据（SysDictData）：二级选项，归属于某个字典类型，如 admin_status 下的 ACTIVE/LOCKED/DISABLED\n"
+            + "- 前端通过 dictType 编码查找对应的 dataList，用 dictValue 匹配实际数据进行翻译展示\n")
     @GetMapping("/all")
     public Result<List<com.hulalv.user.vo.DictVO>> getAllDict() {
         return Result.success(sysDictService.getAllDictForPublic());
@@ -34,14 +41,21 @@ public class SysDictController {
 
     // ======================== Dict Type ========================
 
-    @ApiOperation("创建字典类型")
+    @ApiOperation(value = "创建字典类型", notes = "新建一个字典类型（如：订单状态、证件类型等）。"
+            + "字典类型编码（dictType）全局唯一，创建后不可修改。"
+            + "需要管理员认证，建议仅SUPER_ADMIN/ADMIN角色操作。"
+            + "\n\n**已有字典类型示例**：\n"
+            + "- admin_status（管理员状态）、common_status（通用状态）、login_status（登录状态）\n"
+            + "- order_status（订单状态）、product_status（产品状态）、rating_level（评价等级）\n"
+            + "- id_card_type（证件类型）、gender（性别）、traveler_type（出行人类型）\n"
+            + "- contact_channel_type（联系方式渠道类型）、favorite_resource_type（收藏资源类型）、footprint_resource_type（足迹资源类型）\n")
     @OperationLog(value = "创建字典类型", module = "字典管理")
     @PostMapping("/type")
     public Result<SysDictType> createDictType(@ApiParam("创建字典类型请求") @Valid @RequestBody CreateDictTypeRequest request) {
         return Result.success(sysDictService.createDictType(request));
     }
 
-    @ApiOperation("更新字典类型")
+    @ApiOperation(value = "更新字典类型", notes = "更新字典类型的名称、分类、备注等信息。字典类型编码（dictType）不可修改。")
     @OperationLog(value = "更新字典类型", module = "字典管理")
     @PutMapping("/type/{id}")
     public Result<SysDictType> updateDictType(@ApiParam("字典类型ID") @PathVariable Long id,
@@ -49,7 +63,9 @@ public class SysDictController {
         return Result.success(sysDictService.updateDictType(id, request));
     }
 
-    @ApiOperation("删除字典类型")
+    @ApiOperation(value = "删除字典类型", notes = "删除字典类型及其下所有字典数据（软删除）。"
+            + "如果该字典类型已被业务引用，删除后不影响已有数据，但新的表单将无法选择该字典值。"
+            + "需要管理员认证。")
     @OperationLog(value = "删除字典类型", module = "字典管理")
     @DeleteMapping("/type/{id}")
     public Result<Void> deleteDictType(@ApiParam("字典类型ID") @PathVariable Long id) {
@@ -57,7 +73,8 @@ public class SysDictController {
         return Result.success();
     }
 
-    @ApiOperation("分页查询字典类型")
+    @ApiOperation(value = "分页查询字典类型", notes = "分页查询字典类型列表，支持按分类（category）筛选。"
+            + "字典类型是字典数据的上级分组，管理字典类型即管理有哪些可供前端使用的下拉选项组。")
     @GetMapping("/type")
     public Result<PageResult<SysDictType>> listDictTypes(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -66,7 +83,7 @@ public class SysDictController {
         return Result.success(sysDictService.listDictTypes(page, pageSize, category));
     }
 
-    @ApiOperation("根据ID获取字典类型详情")
+    @ApiOperation(value = "根据ID获取字典类型详情", notes = "获取单个字典类型的详细信息，包括编码、名称、分类、状态等。")
     @GetMapping("/type/{dictTypeId}")
     public Result<SysDictType> getDictTypeById(@ApiParam("字典类型ID") @PathVariable Long dictTypeId) {
         return Result.success(sysDictService.getDictTypeById(dictTypeId));
@@ -74,14 +91,16 @@ public class SysDictController {
 
     // ======================== Dict Data ========================
 
-    @ApiOperation("创建字典数据")
+    @ApiOperation(value = "创建字典数据", notes = "在指定字典类型下新增一条字典数据项。"
+            + "dictValue为前端匹配的值（如ACTIVE），dictLabel为前端展示的标签（如'启用'）。"
+            + "支持树形字典数据（通过parentId设置父级）。")
     @OperationLog(value = "创建字典数据", module = "字典管理")
     @PostMapping("/data")
     public Result<SysDictData> createDictData(@ApiParam("创建字典数据请求") @Valid @RequestBody CreateDictDataRequest request) {
         return Result.success(sysDictService.createDictData(request));
     }
 
-    @ApiOperation("更新字典数据")
+    @ApiOperation(value = "更新字典数据", notes = "更新字典数据项的标签、样式类型、排序号等。dictValue建议不修改以免影响已有业务数据。")
     @OperationLog(value = "更新字典数据", module = "字典管理")
     @PutMapping("/data/{id}")
     public Result<SysDictData> updateDictData(@ApiParam("字典数据ID") @PathVariable Long id,
@@ -89,7 +108,7 @@ public class SysDictController {
         return Result.success(sysDictService.updateDictData(id, request));
     }
 
-    @ApiOperation("删除字典数据")
+    @ApiOperation(value = "删除字典数据", notes = "删除指定字典数据项（软删除）。删除后不影响已引用该字典值的业务数据。")
     @OperationLog(value = "删除字典数据", module = "字典管理")
     @DeleteMapping("/data/{id}")
     public Result<Void> deleteDictData(@ApiParam("字典数据ID") @PathVariable Long id) {
@@ -97,19 +116,23 @@ public class SysDictController {
         return Result.success();
     }
 
-    @ApiOperation("根据ID获取字典数据详情")
+    @ApiOperation(value = "根据ID获取字典数据详情", notes = "获取单个字典数据项的详细信息，包括dictValue、dictLabel、cssClass等。")
     @GetMapping("/data/detail/{dictDataId}")
     public Result<SysDictData> getDictDataById(@ApiParam("字典数据ID") @PathVariable Long dictDataId) {
         return Result.success(sysDictService.getDictDataById(dictDataId));
     }
 
-    @ApiOperation("按类型查询字典数据（树形结构）")
+    @ApiOperation(value = "按类型查询字典数据（树形结构）", notes = "根据字典类型ID查询其下所有字典数据，以树形结构返回（支持父子级字典数据）。"
+            + "用于多级联动下拉框场景（如省市区）。"
+            + "需要管理员认证。")
     @GetMapping("/data/tree/{dictTypeId}")
     public Result<List<SysDictData>> getDictDataTree(@ApiParam("字典类型ID") @PathVariable Long dictTypeId) {
         return Result.success(sysDictService.getDictDataTree(dictTypeId));
     }
 
-    @ApiOperation("按类型查询字典数据")
+    @ApiOperation(value = "按类型查询字典数据", notes = "根据字典类型编码（如order_status）查询其下所有字典数据（平铺列表）。"
+            + "用于单层下拉框场景。"
+            + "需要管理员认证。")
     @GetMapping("/data/{dictType}")
     public Result<List<SysDictData>> getDictDataByType(@ApiParam("字典类型编码") @PathVariable String dictType) {
         return Result.success(sysDictService.getDictDataByType(dictType));

`hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java
index 22b99cb..d58905e 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java
@@ -5,9 +5,9 @@ import com.hulalv.common.result.PageResult;
 import com.hulalv.common.result.Result;
 import com.hulalv.user.dto.CreateJobRequest;
 import com.hulalv.user.dto.UpdateJobRequest;
-import com.hulalv.user.entity.SysJob;
-import com.hulalv.user.entity.SysJobLog;
 import com.hulalv.user.service.SysJobService;
+import com.hulalv.user.vo.SysJobLogVO;
+import com.hulalv.user.vo.SysJobVO;
 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiOperation;
 import io.swagger.annotations.ApiParam;
@@ -24,22 +24,39 @@ public class SysJobController {
 
     private final SysJobService sysJobService;
 
-    @ApiOperation("创建定时任务")
+    @ApiOperation(value = "创建定时任务", notes = "创建新的定时任务。"
+            + "invokeTarget格式为'Bean名称.方法名'（如wechatSyncService.syncAll），方法必须是无参公开方法。"
+            + "cronExpression为标准6位Cron表达式（秒 分 时 日 月 周）。"
+            + "创建后任务默认为暂停状态（PAUSED），需手动调用[恢复任务]接口启用。"
+            + "\n\n**关联字典**：\n"
+            + "- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步\n"
+            + "- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发\n"
+            + "- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停\n\n"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "创建定时任务", module = "定时任务")
     @PostMapping
-    public Result<SysJob> createJob(@ApiParam("创建定时任务请求") @Valid @RequestBody CreateJobRequest request) {
+    public Result<SysJobVO> createJob(@ApiParam("创建定时任务请求") @Valid @RequestBody CreateJobRequest request) {
         return Result.success(sysJobService.createJob(request));
     }
 
-    @ApiOperation("更新定时任务")
+    @ApiOperation(value = "更新定时任务",
+            notes = "更新指定定时任务的名称、Cron表达式、调用目标等信息。\n"
+                + "修改Cron表达式后任务将按新的计划执行。\n\n"
+                + "**关联字典**：\n"
+                + "- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步\n"
+                + "- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发\n\n"
+                + "**权限**：需要SUPER_ADMIN角色。")
     @OperationLog(value = "更新定时任务", module = "定时任务")
     @PutMapping("/{jobId}")
-    public Result<SysJob> updateJob(@ApiParam("定时任务ID") @PathVariable Long jobId,
+    public Result<SysJobVO> updateJob(@ApiParam("定时任务ID") @PathVariable Long jobId,
                                      @ApiParam("更新定时任务请求") @Valid @RequestBody UpdateJobRequest request) {
         return Result.success(sysJobService.updateJob(jobId, request));
     }
 
-    @ApiOperation("删除定时任务")
+    @ApiOperation(value = "删除定时任务",
+            notes = "删除指定的定时任务（软删除），同时从调度器中移除该任务。\n\n"
+                + "**权限**：需要SUPER_ADMIN角色。\n"
+                + "**注意**：删除后任务将不再执行，但历史执行日志仍可查看。")
     @OperationLog(value = "删除定时任务", module = "定时任务")
     @DeleteMapping("/{jobId}")
     public Result<Void> deleteJob(@ApiParam("定时任务ID") @PathVariable Long jobId) {
@@ -47,15 +64,22 @@ public class SysJobController {
         return Result.success();
     }
 
-    @ApiOperation("分页查询定时任务")
+    @ApiOperation(value = "分页查询定时任务", notes = "分页查询定时任务列表。"
+            + "\n\n**关联字典**：\n"
+            + "- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步\n"
+            + "- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发\n"
+            + "- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停")
     @GetMapping
-    public Result<PageResult<SysJob>> listJobs(
+    public Result<PageResult<SysJobVO>> listJobs(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
             @ApiParam("每页条数") @RequestParam(defaultValue = "20") int pageSize) {
         return Result.success(sysJobService.listJobs(page, pageSize));
     }
 
-    @ApiOperation("暂停任务")
+    @ApiOperation(value = "暂停任务", notes = "暂停指定的定时任务，任务状态变为PAUSED。"
+            + "暂停后任务不再按Cron计划执行，但可通过[恢复任务]接口重新启用。"
+            + "\n\n**关联字典**：job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停\n\n"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "暂停任务", module = "定时任务")
     @PostMapping("/{jobId}/pause")
     public Result<Void> pauseJob(@ApiParam("定时任务ID") @PathVariable Long jobId) {
@@ -63,7 +87,10 @@ public class SysJobController {
         return Result.success();
     }
 
-    @ApiOperation("恢复任务")
+    @ApiOperation(value = "恢复任务", notes = "恢复已暂停的定时任务，任务状态变为ACTIVE。"
+            + "恢复后任务按Cron计划继续执行。"
+            + "\n\n**关联字典**：job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停\n\n"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "恢复任务", module = "定时任务")
     @PostMapping("/{jobId}/resume")
     public Result<Void> resumeJob(@ApiParam("定时任务ID") @PathVariable Long jobId) {
@@ -71,7 +98,10 @@ public class SysJobController {
         return Result.success();
     }
 
-    @ApiOperation("立即执行一次")
+    @ApiOperation(value = "立即执行一次", notes = "立即触发一次定时任务的执行，不影响原有的Cron计划。"
+            + "无论任务当前状态是ACTIVE还是PAUSED，都可以手动触发。"
+            + "执行结果可在任务日志中查看。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "立即执行任务", module = "定时任务")
     @PostMapping("/{jobId}/trigger")
     public Result<Void> triggerJob(@ApiParam("定时任务ID") @PathVariable Long jobId) {
@@ -79,9 +109,12 @@ public class SysJobController {
         return Result.success();
     }
 
-    @ApiOperation("查询任务日志")
+    @ApiOperation(value = "查询任务日志", notes = "分页查询指定定时任务的执行日志，按执行时间倒序排列。"
+            + "日志包含执行状态（成功/失败）、执行耗时、异常信息等。"
+            + "\n\n**关联字典**：job_log_status（日志状态）：SUCCESS=成功, FAIL=失败\n\n"
+            + "需要管理员认证。")
     @GetMapping("/{jobId}/logs")
-    public Result<PageResult<SysJobLog>> listJobLogs(
+    public Result<PageResult<SysJobLogVO>> listJobLogs(
             @ApiParam("定时任务ID") @PathVariable Long jobId,
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
             @ApiParam("每页条数") @RequestParam(defaultValue = "20") int pageSize) {

`hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java
index 46e8615..44e4293 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java
@@ -24,14 +24,27 @@ public class SysMenuController {
 
     private final SysMenuService sysMenuService;
 
-    @ApiOperation("创建菜单")
+    @ApiOperation(value = "创建菜单", notes = "创建新的菜单/目录/按钮。"
+            + "menuType取值：DIRECTORY=目录（含子菜单） MENU=页面菜单 BUTTON=操作按钮。"
+            + "目录和菜单需设置path路由路径，菜单还需设置component组件路径。"
+            + "按钮类型需设置permissionCode权限标识（如system:user:add）。"
+            + "需要SUPER_ADMIN角色。"
+            + "\n\n**关联字典**：\n"
+            + "- menu_type（菜单类型）：请求/返回字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮）\n"
+            + "- common_status（通用状态）：返回字段status")
     @OperationLog(value = "创建菜单", module = "菜单管理")
     @PostMapping
     public Result<SysMenu> createMenu(@ApiParam("创建菜单请求") @Valid @RequestBody CreateMenuRequest request) {
         return Result.success(sysMenuService.createMenu(request));
     }
 
-    @ApiOperation("更新菜单")
+    @ApiOperation(value = "更新菜单",
+            notes = "更新指定菜单的名称、路径、组件、图标、排序、状态等信息。\n\n"
+                + "**权限**：需要SUPER_ADMIN角色。\n"
+                + "**注意**：修改后需清除 Redis 菜单缓存才能生效。\n\n"
+                + "**关联字典**：\n"
+                + "- menu_type（菜单类型）：请求字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮）\n"
+                + "- common_status（通用状态）：请求字段status")
     @OperationLog(value = "更新菜单", module = "菜单管理")
     @PutMapping("/{menuId}")
     public Result<SysMenu> updateMenu(@ApiParam("菜单ID") @PathVariable Long menuId,
@@ -39,7 +52,11 @@ public class SysMenuController {
         return Result.success(sysMenuService.updateMenu(menuId, request));
     }
 
-    @ApiOperation("删除菜单")
+    @ApiOperation(value = "删除菜单",
+            notes = "删除指定的菜单/目录/按钮（软删除）。\n\n"
+                + "**权限**：需要SUPER_ADMIN角色。\n"
+                + "**注意**：如果该菜单有子菜单，需先删除子菜单才能删除父菜单。"
+                + "删除后需清除 Redis 菜单缓存才能生效。")
     @OperationLog(value = "删除菜单", module = "菜单管理")
     @DeleteMapping("/{menuId}")
     public Result<Void> deleteMenu(@ApiParam("菜单ID") @PathVariable Long menuId) {
@@ -47,25 +64,42 @@ public class SysMenuController {
         return Result.success();
     }
 
-    @ApiOperation("获取菜单详情")
+    @ApiOperation(value = "获取菜单详情",
+            notes = "获取指定菜单的详细信息，包括名称、路径、组件、图标、排序、权限标识等。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- menu_type（菜单类型）：返回字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮）\n"
+                + "- common_status（通用状态）：返回字段status")
     @GetMapping("/{menuId}")
     public Result<SysMenu> getMenu(@ApiParam("菜单ID") @PathVariable Long menuId) {
         return Result.success(sysMenuService.getMenuById(menuId));
     }
 
-    @ApiOperation("获取完整菜单树")
+    @ApiOperation(value = "获取完整菜单树", notes = "获取系统所有菜单的完整树形结构。"
+            + "用于角色权限配置页面展示完整的菜单树供勾选。"
+            + "仅SUPER_ADMIN可查看完整菜单树。"
+            + "需要管理员认证。"
+            + "\n\n**关联字典**：\n"
+            + "- menu_type（菜单类型）：返回字段menuType\n"
+            + "- common_status（通用状态）：返回字段status")
     @GetMapping("/tree")
     public Result<List<SysMenu>> getMenuTree() {
         return Result.success(sysMenuService.getMenuTree());
     }
 
-    @ApiOperation("获取角色菜单树")
+    @ApiOperation(value = "获取角色菜单树",
+            notes = "获取指定角色已分配的菜单树形结构。\n"
+                + "用于角色权限配置页面，展示该角色已拥有的菜单权限。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/tree/role/{roleId}")
     public Result<List<SysMenu>> getMenuTreeByRoleId(@ApiParam("角色ID") @PathVariable Long roleId) {
         return Result.success(sysMenuService.getMenuTreeByRoleId(roleId));
     }
 
-    @ApiOperation("获取当前管理员菜单")
+    @ApiOperation(value = "获取当前管理员菜单", notes = "获取当前登录管理员的菜单树（基于其当前角色的权限）。"
+            + "SUPER_ADMIN角色返回完整菜单树，其他角色返回已授权的菜单子集。"
+            + "前端登录后调用此接口动态生成路由和侧边栏菜单。"
+            + "需要管理员认证。")
     @GetMapping("/my")
     public Result<List<SysMenu>> getMyMenus(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");

`hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java
index 1e4979d..52f6507 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java
@@ -25,14 +25,19 @@ public class SysRoleController {
 
     private final SysRoleService sysRoleService;
 
-    @ApiOperation("创建角色")
+    @ApiOperation(value = "创建角色", notes = "创建新的系统角色。"
+            + "角色标识（roleKey）全局唯一，创建后不可修改，用于代码中的权限判断。"
+            + "创建后需通过[分配菜单权限]接口为角色授权菜单。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "创建角色", module = "角色管理")
     @PostMapping
     public Result<SysRole> createRole(@ApiParam("创建角色请求") @Valid @RequestBody CreateRoleRequest request) {
         return Result.success(sysRoleService.createRole(request));
     }
 
-    @ApiOperation("更新角色")
+    @ApiOperation(value = "更新角色", notes = "更新角色名称、状态等信息。角色标识（roleKey）不可修改。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：ACTIVE=启用, DISABLED=禁用\n")
     @OperationLog(value = "更新角色", module = "角色管理")
     @PutMapping("/{roleId}")
     public Result<SysRole> updateRole(@ApiParam("角色ID") @PathVariable Long roleId,
@@ -40,7 +45,10 @@ public class SysRoleController {
         return Result.success(sysRoleService.updateRole(roleId, request));
     }
 
-    @ApiOperation("删除角色")
+    @ApiOperation(value = "删除角色", notes = "删除指定角色（软删除）。"
+            + "如果该角色下还有关联的管理员，将无法删除，需先解除绑定关系。"
+            + "内置角色（SUPER_ADMIN等）不可删除。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "删除角色", module = "角色管理")
     @DeleteMapping("/{roleId}")
     public Result<Void> deleteRole(@ApiParam("角色ID") @PathVariable Long roleId) {
@@ -48,13 +56,17 @@ public class SysRoleController {
         return Result.success();
     }
 
-    @ApiOperation("获取角色详情(含菜单ID)")
+    @ApiOperation(value = "获取角色详情(含菜单ID)", notes = "获取角色基本信息及其已分配的菜单ID列表。"
+            + "返回role对象和menuIds数组，用于角色编辑页面回显已勾选的菜单。"
+            + "需要管理员认证。")
     @GetMapping("/{roleId}")
     public Result<java.util.Map<String, Object>> getRoleDetail(@ApiParam("角色ID") @PathVariable Long roleId) {
         return Result.success(sysRoleService.getRoleDetail(roleId));
     }
 
-    @ApiOperation("分页查询角色")
+    @ApiOperation(value = "分页查询角色", notes = "分页查询系统角色列表，支持按状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：ACTIVE=启用, DISABLED=禁用（筛选条件+列表展示）\n")
     @GetMapping
     public Result<PageResult<SysRole>> listRoles(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -63,13 +75,19 @@ public class SysRoleController {
         return Result.success(sysRoleService.listRoles(page, pageSize, status));
     }
 
-    @ApiOperation("获取所有角色(下拉)")
+    @ApiOperation(value = "获取所有角色(下拉)", notes = "获取所有状态正常的角色列表，用于下拉选择框。"
+            + "不分页，返回全部角色。创建管理员、筛选管理员列表时使用。"
+            + "需要管理员认证。")
     @GetMapping("/all")
     public Result<List<SysRole>> getAllRoles() {
         return Result.success(sysRoleService.getAllRoles());
     }
 
-    @ApiOperation("分配菜单权限")
+    @ApiOperation(value = "分配菜单权限", notes = "为指定角色分配菜单权限（全量覆盖模式）。"
+            + "传入的menuIds将完全替换该角色原有的菜单权限。"
+            + "分配后该角色的所有在线管理员下次请求 /admin/menu/my 时会获取到新的菜单树。"
+            + "注意：需同步清除Redis中的菜单缓存，否则前端拿到的是旧菜单。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "分配菜单权限", module = "角色管理")
     @PutMapping("/{roleId}/menus")
     public Result<Void> assignMenus(@ApiParam("角色ID") @PathVariable Long roleId,

`hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java
index 5f71654..ac3f257 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java
@@ -22,7 +22,15 @@ public class TravelerController {
 
     private final TravelerService travelerService;
 
-    @ApiOperation("新增出行人")
+    @ApiOperation(value = "新增出行人", notes = "为当前用户添加一位出行人信息，用于下单时选择。"
+            + "出行人类型（成人/儿童/婴儿）根据出生日期自动判断，无需手动传入。"
+            + "如果传入身份证号，后端自动校验格式并解析性别。"
+            + "每个用户最多可添加20位出行人。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- gender（性别）：请求/返回字段gender（0=女, 1=男）\n"
+            + "- id_card_type（证件类型）：请求/返回字段idCardType（ID_CARD=身份证, PASSPORT=护照等）\n"
+            + "- traveler_type（出行人类型）：返回字段travelerType（ADULT=成人, CHILD=儿童, INFANT=婴儿，自动计算）")
     @PostMapping
     public Result<Traveler> addTraveler(HttpServletRequest request,
                                           @ApiParam("出行人信息") @Valid @RequestBody TravelerRequest travelerRequest) {
@@ -31,7 +39,14 @@ public class TravelerController {
         return Result.success(traveler);
     }
 
-    @ApiOperation("出行人列表")
+    @ApiOperation(value = "出行人列表", notes = "获取当前用户的所有出行人列表。"
+            + "如果用户已完成实名认证（realName不为空），列表首项会自动注入一个'本人'虚拟出行人（travelerId=0）。"
+            + "默认出行人排在前面，其余按创建时间排序。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- gender（性别）：返回字段gender\n"
+            + "- id_card_type（证件类型）：返回字段idCardType\n"
+            + "- traveler_type（出行人类型）：返回字段travelerType")
     @GetMapping
     public Result<List<Traveler>> listTravelers(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
@@ -39,7 +54,11 @@ public class TravelerController {
         return Result.success(travelers);
     }
 
-    @ApiOperation("出行人详情")
+    @ApiOperation(value = "出行人详情", notes = "获取指定出行人的详细信息。"
+            + "\n\n**关联字典**：\n"
+            + "- gender（性别）：返回字段gender\n"
+            + "- id_card_type（证件类型）：返回字段idCardType\n"
+            + "- traveler_type（出行人类型）：返回字段travelerType")
     @GetMapping("/{travelerId}")
     public Result<Traveler> getTraveler(HttpServletRequest request,
                                           @ApiParam("出行人ID") @PathVariable Long travelerId) {
@@ -48,7 +67,11 @@ public class TravelerController {
         return Result.success(traveler);
     }
 
-    @ApiOperation("更新出行人")
+    @ApiOperation(value = "更新出行人", notes = "更新指定出行人的信息。"
+            + "\n\n**关联字典**：\n"
+            + "- gender（性别）：请求/返回字段gender\n"
+            + "- id_card_type（证件类型）：请求/返回字段idCardType\n"
+            + "- traveler_type（出行人类型）：返回字段travelerType（自动计算）")
     @PutMapping("/{travelerId}")
     public Result<Traveler> updateTraveler(HttpServletRequest request,
                                               @ApiParam("出行人ID") @PathVariable Long travelerId,
@@ -58,7 +81,10 @@ public class TravelerController {
         return Result.success(traveler);
     }
 
-    @ApiOperation("删除出行人")
+    @ApiOperation(value = "删除出行人",
+            notes = "删除指定的出行人记录（软删除）。\n\n"
+                + "**权限**：需要小程序用户认证。\n"
+                + "**注意**：如果该出行人已关联到未完成的订单，删除不影响订单中的出行人快照数据。")
     @DeleteMapping("/{travelerId}")
     public Result<Void> deleteTraveler(HttpServletRequest request,
                                           @ApiParam("出行人ID") @PathVariable Long travelerId) {
@@ -67,7 +93,10 @@ public class TravelerController {
         return Result.success();
     }
 
-    @ApiOperation("设为默认出行人")
+    @ApiOperation(value = "设为默认出行人", notes = "将指定出行人设为默认。"
+            + "每个用户只能有一个默认出行人，设置新的默认会自动取消原来的默认。"
+            + "默认出行人在下单时会被自动选中。"
+            + "需要小程序用户认证。")
     @PutMapping("/{travelerId}/default")
     public Result<Void> setDefault(HttpServletRequest request,
                                       @ApiParam("出行人ID") @PathVariable Long travelerId) {

`hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java
index f5d5dc0..24ecd04 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java
@@ -29,28 +29,42 @@ public class UserController {
     private final SmsService smsService;
     private final FavoriteService favoriteService;
 
-    @ApiOperation("发送短信验证码")
+    @ApiOperation(value = "发送短信验证码", notes = "向指定手机号发送6位数字短信验证码，用于小程序手机号登录。"
+            + "同一手机号60秒内不可重复发送，每日最多发送10次。"
+            + "验证码有效期5分钟。"
+            + "无需认证即可调用。")
     @PostMapping("/sms/send")
     public Result<Void> sendSmsCode(@ApiParam("发送短信验证码请求") @Valid @RequestBody SendSmsRequest request) {
         smsService.sendVerificationCode(request.getPhone());
         return Result.success();
     }
 
-    @ApiOperation("手机号验证码登录")
+    @ApiOperation(value = "手机号验证码登录", notes = "小程序用户通过手机号+短信验证码登录。"
+            + "首次登录自动注册账号，返回JWT Token。"
+            + "登录成功后若needProfile=true，表示需要补充个人信息（实名认证），前端应跳转到信息补充页。"
+            + "无需认证即可调用。")
     @PostMapping("/login/sms")
     public Result<LoginResponse> loginBySms(@ApiParam("短信验证码登录请求") @Valid @RequestBody SmsLoginRequest request) {
         LoginResponse response = userService.loginBySms(request);
         return Result.success(response);
     }
 
-    @ApiOperation("微信登录")
+    @ApiOperation(value = "微信登录", notes = "小程序用户通过微信授权码（wx.login获取的code）登录。"
+            + "可选传入phoneCode用于获取手机号绑定，avatar和nickname用于设置头像昵称。"
+            + "首次登录自动注册，返回JWT Token。needProfile=true表示需补充实名信息。"
+            + "无需认证即可调用。")
     @PostMapping("/login")
     public Result<LoginResponse> login(@ApiParam("微信登录请求") @Valid @RequestBody LoginRequest request) {
         LoginResponse response = userService.login(request);
         return Result.success(response);
     }
 
-    @ApiOperation("获取用户信息")
+    @ApiOperation(value = "获取用户信息", notes = "获取当前登录用户的个人资料，包括昵称、头像、手机号（脱敏）、实名信息等。"
+            + "手机号返回脱敏格式（如138****0000），证件号同样脱敏处理。"
+            + "需要小程序用户认证（Token中的userId）。"
+            + "\n\n**关联字典**：\n"
+            + "- id_card_type（证件类型）：ID_CARD=身份证, PASSPORT=护照\n"
+            + "- gender（性别）：0=女, 1=男\n")
     @GetMapping("/profile")
     public Result<UserVO> getProfile(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
@@ -58,7 +72,14 @@ public class UserController {
         return Result.success(user);
     }
 
-    @ApiOperation("更新用户信息")
+    @ApiOperation(value = "更新用户信息", notes = "更新当前用户的个人资料。"
+            + "首次登录补充信息时realName/idCardType/idCardNo为必填（使用ProfileCompletion验证组）。"
+            + "如果传入身份证号，后端自动解析性别和出生日期。"
+            + "更新手机号后会自动绑定匹配的待绑定订单。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- id_card_type（证件类型）：ID_CARD=身份证, PASSPORT=护照（请求参数idCardType）\n"
+            + "- gender（性别）：0=女, 1=男\n")
     @PutMapping("/profile")
     public Result<UserVO> updateProfile(HttpServletRequest request,
                                        @ApiParam("更新用户信息请求") @Valid @RequestBody UpdateProfileRequest updateRequest) {
@@ -67,7 +88,8 @@ public class UserController {
         return Result.success(user);
     }
 
-    @ApiOperation("用户登出")
+    @ApiOperation(value = "用户登出", notes = "清除当前用户的登录状态并使Token失效。"
+            + "需要小程序用户认证。")
     @PostMapping("/logout")
     public Result<Void> logout(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
@@ -75,7 +97,10 @@ public class UserController {
         return Result.success();
     }
 
-    @ApiOperation("注销账号")
+    @ApiOperation(value = "注销账号", notes = "永久注销当前用户账号（软删除）。"
+            + "注销后该账号的openid和手机号将被释放，可用于重新注册。"
+            + "注销操作不可撤销，请谨慎调用。"
+            + "需要小程序用户认证。")
     @DeleteMapping("/account")
     public Result<Void> deleteAccount(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
@@ -83,7 +108,12 @@ public class UserController {
         return Result.success();
     }
 
-    @ApiOperation("检查是否已收藏")
+    @ApiOperation(value = "检查是否已收藏", notes = "检查当前用户是否已收藏指定类型的资源。"
+            + "返回true=已收藏，false=未收藏。"
+            + "targetType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT/EXPLORE等。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索（请求参数targetType）\n")
     @GetMapping("/favorite/check")
     public Result<Boolean> checkFavorite(HttpServletRequest request,
                                           @ApiParam("目标类型") @RequestParam String targetType,

`hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java
index 2b68e9c..03cca6a 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java
@@ -23,7 +23,10 @@ public class WechatSyncController {
 
     private final WechatSyncService wechatSyncService;
 
-    @ApiOperation("手动同步部门")
+    @ApiOperation(value = "手动同步部门", notes = "从企业微信拉取最新的部门列表并同步到本地数据库。"
+            + "通常在企业微信后台调整组织架构后手动触发。"
+            + "也可通过定时任务自动执行。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "手动同步部门", module = "企业微信同步")
     @PostMapping("/sync/departments")
     public Result<Void> syncDepartments() {
@@ -31,7 +34,10 @@ public class WechatSyncController {
         return Result.success();
     }
 
-    @ApiOperation("手动同步用户")
+    @ApiOperation(value = "手动同步用户", notes = "从企业微信拉取所有部门的成员列表并同步到本地数据库。"
+            + "包括姓名、手机号、职位、部门归属等信息。"
+            + "需先同步部门再同步用户，或直接使用[同步全部]接口。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "手动同步用户", module = "企业微信同步")
     @PostMapping("/sync/users")
     public Result<Void> syncUsers() {
@@ -39,7 +45,10 @@ public class WechatSyncController {
         return Result.success();
     }
 
-    @ApiOperation("手动同步全部（部门+用户）")
+    @ApiOperation(value = "手动同步全部（部门+用户）", notes = "一键同步企业微信的部门和用户数据，先同步部门再同步用户。"
+            + "推荐使用此接口而非单独同步，确保部门和用户数据一致性。"
+            + "同步过程为异步执行，接口立即返回成功。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "手动同步全部", module = "企业微信同步")
     @PostMapping("/sync/all")
     public Result<Void> syncAll() {
@@ -47,7 +56,13 @@ public class WechatSyncController {
         return Result.success();
     }
 
-    @ApiOperation("查询企业微信用户（分页+搜索）")
+    @ApiOperation(value = "查询企业微信用户（分页+搜索）", notes = "分页查询已同步的企业微信用户列表。"
+            + "支持按姓名/手机号/职位关键词搜索，按部门ID和状态筛选。"
+            + "status取值：1=已激活 2=已禁用 4=未关注。"
+            + "用于管理员绑定企微账号时选择企微用户。"
+            + "需要管理员认证。"
+            + "\n\n**关联字典**：\n"
+            + "- wechat_user_status（企微用户状态）：请求参数status和返回字段status（1=已激活, 2=已禁用, 4=未关注）")
     @GetMapping("/users")
     public Result<PageResult<WechatUser>> listWechatUsers(
             @ApiParam("页码") @RequestParam(defaultValue = "1") Integer page,
@@ -58,21 +73,29 @@ public class WechatSyncController {
         return Result.success(wechatSyncService.listWechatUsers(page, pageSize, keyword, deptId, status));
     }
 
-    @ApiOperation("部门列表（部门管理页面）")
+    @ApiOperation(value = "部门列表（部门管理页面）",
+            notes = "获取已同步的所有企业微信部门列表（平铺结构），用于部门管理页面展示。\n"
+                + "包含部门ID、名称、上级部门ID、排序等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/departments")
     public Result<List<WechatDepartment>> listAllDepartments() {
         List<WechatDepartment> departments = wechatSyncService.listAllDepartments();
         return Result.success(departments);
     }
 
-    @ApiOperation("部门树（下拉筛选）")
+    @ApiOperation(value = "部门树（下拉筛选）", notes = "以树形结构返回企业微信部门数据。"
+            + "用于部门筛选下拉框，每个节点包含id/label/children。"
+            + "需要管理员认证。")
     @GetMapping("/departments/tree")
     public Result<List<Map<String, Object>>> listDepartmentsTree() {
         List<Map<String, Object>> tree = wechatSyncService.listDepartmentsTree();
         return Result.success(tree);
     }
 
-    @ApiOperation("同步状态（最后同步时间）")
+    @ApiOperation(value = "同步状态（最后同步时间）",
+            notes = "获取企业微信数据的最后同步时间和状态。\n"
+                + "返回部门和用户各自的最后同步时间，用于管理页面展示同步状态。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/sync/status")
     public Result<Map<String, Object>> getSyncStatus() {
         Map<String, Object> status = wechatSyncService.getSyncStatus();

`hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java` (M)

接口变更 diff：

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java b/hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java
index d2b7b8d..aa20c4b 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java
@@ -45,7 +45,10 @@ public class AdminNotificationController {
 
     // ==================== 事件配置 ====================
 
-    @ApiOperation("获取通知配置列表（按分类分组）")
+    @ApiOperation(value = "获取通知配置列表（按分类分组）", notes = "获取所有通知事件配置，按消息分类（categoryCode）分组返回。"
+            + "每个事件配置包含各通知渠道的开关状态（smsEnabled/inappEnabled/weworkEnabled等）。"
+            + "\n\n**关联字典**：\n"
+            + "- notification_channel（通知渠道）：sms=短信, inapp=站内信, wework=企业微信, miniapp_subscribe=小程序订阅消息, official_account=公众号模板消息\n")
     @GetMapping("/config")
     public Result<Map<String, List<EventConfigVO>>> listConfigs() {
         Map<String, List<NotificationEventConfig>> grouped = configService.listGroupedByCategory();
@@ -66,7 +69,9 @@ public class AdminNotificationController {
         return Result.success(result);
     }
 
-    @ApiOperation("切换通道开关")
+    @ApiOperation(value = "切换通道开关", notes = "切换指定通知事件的某个渠道开关。"
+            + "channel取值：sms/inapp/wework/miniapp_subscribe/official_account。"
+            + "注意：只允许开启渠道，不建议关闭已有渠道。")
     @PutMapping("/config/{id}/toggle")
     public Result<Void> toggleChannel(@PathVariable Long id,
                                        @Valid @RequestBody ChannelToggleRequest request) {
@@ -74,7 +79,10 @@ public class AdminNotificationController {
         return Result.success();
     }
 
-    @ApiOperation("编辑事件配置详情")
+    @ApiOperation(value = "编辑事件配置详情",
+            notes = "更新指定通知事件配置的详细信息，包括模板内容、接收人规则等。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：修改模板内容后会立即影响后续的通知发送。")
     @PutMapping("/config/{id}")
     public Result<Void> updateConfig(@PathVariable Long id,
                                       @Valid @RequestBody EventConfigUpdateRequest request) {
@@ -84,7 +92,11 @@ public class AdminNotificationController {
         return Result.success();
     }
 
-    @ApiOperation("测试发送")
+    @ApiOperation(value = "测试发送",
+            notes = "使用测试数据触发一次通知发送，验证通知配置是否正确。\n"
+                + "会使用预设的测试参数（订单号、产品名等）填充模板。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：需指定 testUserId 或 testAdminId 作为接收人，发送结果可在发送日志中查看。")
     @PostMapping("/config/{id}/test")
     public Result<String> testSend(@PathVariable Long id,
                                     @Valid @RequestBody TestSendRequest request) {
@@ -125,7 +137,10 @@ public class AdminNotificationController {
 
     // ==================== 消息分类 ====================
 
-    @ApiOperation("获取消息分类列表")
+    @ApiOperation(value = "获取消息分类列表",
+            notes = "获取所有通知消息分类，包括分类编码、名称、图标、描述等。\n"
+                + "消息分类用于将通知事件归组管理（如订单消息、系统消息等）。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/categories")
     public Result<List<MessageCategoryVO>> listCategories() {
         List<MessageCategory> categories = categoryService.listAll();
@@ -135,7 +150,10 @@ public class AdminNotificationController {
         return Result.success(voList);
     }
 
-    @ApiOperation("创建消息分类")
+    @ApiOperation(value = "创建消息分类",
+            notes = "创建新的通知消息分类，用于归组管理通知事件。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：分类编码（code）必须唯一，创建后不可修改。")
     @PostMapping("/categories")
     public Result<Void> createCategory(@Valid @RequestBody CategoryRequest request) {
         MessageCategory category = new MessageCategory();
@@ -148,7 +166,10 @@ public class AdminNotificationController {
         return Result.success();
     }
 
-    @ApiOperation("更新消息分类")
+    @ApiOperation(value = "更新消息分类",
+            notes = "更新指定消息分类的名称、图标、描述、排序等信息。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：分类编码（code）不可修改。")
     @PutMapping("/categories/{id}")
     public Result<Void> updateCategory(@PathVariable Long id,
                                         @Valid @RequestBody CategoryRequest request) {
@@ -161,7 +182,10 @@ public class AdminNotificationController {
         return Result.success();
     }
 
-    @ApiOperation("删除消息分类")
+    @ApiOperation(value = "删除消息分类",
+            notes = "删除指定的消息分类。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：如果该分类下有关联的通知事件配置，需先移除关联后才能删除。")
     @DeleteMapping("/categories/{id}")
     public Result<Void> deleteCategory(@PathVariable Long id) {
         categoryService.delete(id);
@@ -170,13 +194,18 @@ public class AdminNotificationController {
 
     // ==================== 发送日志 ====================
 
-    @ApiOperation("查询发送日志")
+    @ApiOperation(value = "查询发送日志", notes = "分页查询通知发送日志，支持按事件编码、渠道、状态等筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- notification_channel（通知渠道）：返回字段channel\n"
+            + "- notification_send_status（发送状态）：返回字段status（SUCCESS=成功, FAILED=失败, SKIPPED=跳过）\n")
     @GetMapping("/logs")
     public Result<PageResult<SendLogVO>> queryLogs(LogQueryRequest request) {
         return Result.success(sendLogService.queryLogs(request));
     }
 
-    @ApiOperation("获取发送统计")
+    @ApiOperation(value = "获取发送统计",
+            notes = "获取通知发送的统计数据，包括总发送数、成功数、失败数、各渠道发送量等。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/logs/stats")
     public Result<SendLogStatsVO> getLogStats() {
         return Result.success(sendLogService.getStats());
@@ -184,7 +213,11 @@ public class AdminNotificationController {
 
     // ==================== 自定义推送 ====================
 
-    @ApiOperation("自定义推送")
+    @ApiOperation(value = "自定义推送",
+            notes = "向指定用户发送自定义通知消息，支持选择推送渠道和目标用户。\n"
+                + "用于运营人员手动推送活动通知、系统公告等。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：推送记录会记入发送日志。")
     @PostMapping("/custom-push")
     public Result<CustomPushResultVO> customPush(@Valid @RequestBody CustomPushRequest request,
                                                   HttpServletRequest httpRequest) {
@@ -193,7 +226,10 @@ public class AdminNotificationController {
         return Result.success(result);
     }
 
-    @ApiOperation("搜索用户（自定义推送选择目标）")
+    @ApiOperation(value = "搜索用户（自定义推送选择目标）",
+            notes = "按关键词搜索C端用户，用于自定义推送时选择推送目标。\n"
+                + "支持按真实姓名或手机号模糊搜索，最多返回20条结果。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/custom-push/users")
     public Result<List<UserSimpleVO>> searchUsersForPush(@RequestParam(required = false) String keyword) {
         LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<User>()

DTO/VO 字段变更

`hl-user-service/src/main/java/com/hulalv/user/vo/SysJobLogVO.java` (A)

新增

package com.hulalv.user.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.time.LocalDateTime;

@Data
@ApiModel("定时任务执行日志")
public class SysJobLogVO {
    @ApiModelProperty("日志ID")
    private Long jobLogId;

    @ApiModelProperty("任务ID")
    private Long jobId;

    @ApiModelProperty("任务名称")
    private String jobName;

    @ApiModelProperty("调用目标")
    private String invokeTarget;

    @ApiModelProperty(value = "执行状态", notes = "字典类型：job_log_status。可选值：SUCCESS=成功, FAIL=失败")
    private String status;

    @ApiModelProperty("执行结果/异常信息")
    private String message;

    @ApiModelProperty("开始时间")
    private LocalDateTime startTime;

    @ApiModelProperty("结束时间")
    private LocalDateTime endTime;

    @ApiModelProperty("创建时间")
    private LocalDateTime createdAt;
}

`hl-user-service/src/main/java/com/hulalv/user/vo/SysJobVO.java` (A)

新增

package com.hulalv.user.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.time.LocalDateTime;

@Data
@ApiModel("定时任务信息")
public class SysJobVO {
    @ApiModelProperty("任务ID")
    private Long jobId;

    @ApiModelProperty("任务名称")
    private String jobName;

    @ApiModelProperty(value = "任务分组", notes = "字典类型：job_group。可选值：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步")
    private String jobGroup;

    @ApiModelProperty("调用目标（Bean名称.方法名）")
    private String invokeTarget;

    @ApiModelProperty("Cron表达式")
    private String cronExpression;

    @ApiModelProperty(value = "计划执行策略", notes = "字典类型：job_misfire_policy。可选值：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发")
    private String misfirePolicy;

    @ApiModelProperty("是否允许并发执行")
    private Boolean concurrent;

    @ApiModelProperty(value = "任务状态", notes = "字典类型：job_status。可选值：ACTIVE=启用, PAUSED=已暂停")
    private String status;

    @ApiModelProperty("备注")
    private String remark;

    @ApiModelProperty("创建时间")
    private LocalDateTime createdAt;

    @ApiModelProperty("更新时间")
    private LocalDateTime updatedAt;
}

`hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java b/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java
index cc334e0..001c095 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java
@@ -1,15 +1,33 @@
 package com.hulalv.callback.msgaudit.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("聊天消息VO")
 public class ChatMessageVO {
+    @ApiModelProperty("消息ID")
     private String msgId;
+
+    @ApiModelProperty("发送人ID")
     private String fromUser;
+
+    @ApiModelProperty("发送人姓名")
     private String fromUserName;
+
+    @ApiModelProperty("发送人头像")
     private String fromUserAvatar;
+
+    @ApiModelProperty("群聊ID")
     private String roomId;
+
+    @ApiModelProperty("消息时间戳")
     private Long msgTime;
+
+    @ApiModelProperty("消息类型")
     private String msgType;
+
+    @ApiModelProperty("消息内容")
     private String content;
 }

`hl-common/src/main/java/com/hulalv/common/dto/AdminBasicDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/AdminBasicDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/AdminBasicDTO.java
index 4384bbc..d7ae755 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/AdminBasicDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/AdminBasicDTO.java
@@ -1,14 +1,26 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 import java.io.Serializable;
 
 @Data
+@ApiModel("管理员基本信息")
 public class AdminBasicDTO implements Serializable {
+    @ApiModelProperty("管理员ID")
     private Long adminId;
+
+    @ApiModelProperty("用户名")
     private String username;
+
+    @ApiModelProperty("头像URL")
     private String avatarUrl;
+
+    @ApiModelProperty("企微用户ID")
     private String wechatUserid;
+
+    @ApiModelProperty("企微用户名称")
     private String wechatName;
 }

`hl-common/src/main/java/com/hulalv/common/dto/DepartmentDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/DepartmentDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/DepartmentDTO.java
index 54e49c6..d957404 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/DepartmentDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/DepartmentDTO.java
@@ -1,12 +1,20 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 import java.io.Serializable;
 
 @Data
+@ApiModel("部门信息")
 public class DepartmentDTO implements Serializable {
+    @ApiModelProperty("部门ID")
     private Long deptId;
+
+    @ApiModelProperty("部门名称")
     private String deptName;
+
+    @ApiModelProperty("上级部门ID")
     private Long parentId;
 }

`hl-common/src/main/java/com/hulalv/common/dto/ExternalContactEventDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/ExternalContactEventDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/ExternalContactEventDTO.java
index b460471..b5d3084 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/ExternalContactEventDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/ExternalContactEventDTO.java
@@ -1,13 +1,18 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("外部联系人事件")
 public class ExternalContactEventDTO {
-    /** add_external_contact / del_follow_user / del_external_contact / edit_external_contact */
+    @ApiModelProperty("变更类型: add_external_contact/del_follow_user/del_external_contact/edit_external_contact")
     private String changeType;
-    /** Employee enterprise WeChat userid */
+
+    @ApiModelProperty("员工企微用户ID")
     private String userId;
-    /** External contact ID */
+
+    @ApiModelProperty("外部联系人ID")
     private String externalUserId;
 }

`hl-common/src/main/java/com/hulalv/common/dto/FileBindRefsDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/FileBindRefsDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/FileBindRefsDTO.java
index dc20c8c..dda68cc 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/FileBindRefsDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/FileBindRefsDTO.java
@@ -1,5 +1,7 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,8 +11,14 @@ import java.util.List;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("文件绑定引用请求")
 public class FileBindRefsDTO {
+    @ApiModelProperty("业务类型")
     private String bizType;
+
+    @ApiModelProperty("业务ID")
     private Long bizId;
+
+    @ApiModelProperty("文件ID列表")
     private List<Long> fileIds;
 }

`hl-common/src/main/java/com/hulalv/common/dto/FileUnbindRefsDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/FileUnbindRefsDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/FileUnbindRefsDTO.java
index 5cc541a..9a26827 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/FileUnbindRefsDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/FileUnbindRefsDTO.java
@@ -1,5 +1,7 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -7,7 +9,11 @@ import lombok.NoArgsConstructor;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("文件解绑引用请求")
 public class FileUnbindRefsDTO {
+    @ApiModelProperty("业务类型")
     private String bizType;
+
+    @ApiModelProperty("业务ID")
     private Long bizId;
 }

`hl-common/src/main/java/com/hulalv/common/dto/OrderPayInfoDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/OrderPayInfoDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/OrderPayInfoDTO.java
index 2b8b700..1661e45 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/OrderPayInfoDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/OrderPayInfoDTO.java
@@ -1,5 +1,7 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import java.math.BigDecimal;
 
@@ -7,19 +9,41 @@ import java.math.BigDecimal;
  * Order payment info DTO (order-service -> payment-service)
  */
 @Data
+@ApiModel("订单支付信息")
 public class OrderPayInfoDTO {
+    @ApiModelProperty("订单ID")
     private Long orderId;
+
+    @ApiModelProperty("订单编号")
     private String orderNo;
+
+    @ApiModelProperty("用户ID")
     private Long userId;
+
+    @ApiModelProperty("商户号")
     private String mchId;
+
+    @ApiModelProperty("总价")
     private BigDecimal totalPrice;
+
+    @ApiModelProperty("优惠金额")
     private BigDecimal discountAmount;
+
+    @ApiModelProperty("定金金额")
     private BigDecimal depositAmount;
+
+    @ApiModelProperty("已支付金额")
     private BigDecimal paidAmount;
-    /** 支付模式: FULL=全款 DEPOSIT=定金+尾款 */
+
+    @ApiModelProperty("支付模式: FULL=全款, DEPOSIT=定金+尾款")
     private String paymentMode;
+
+    @ApiModelProperty("订单状态")
     private String status;
+
+    @ApiModelProperty("产品名称")
     private String productName;
-    /** 是否预定产品: true=预定(定金可不填出行人) false=非预定(支付前必须填出行人) */
+
+    @ApiModelProperty("是否预定产品: true=预定(定金可不填出行人), false=非预定(支付前必须填出行人)")
     private Boolean isBooking;
 }

`hl-common/src/main/java/com/hulalv/common/dto/PaymentResultDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/PaymentResultDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/PaymentResultDTO.java
index f39ebfa..7becb52 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/PaymentResultDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/PaymentResultDTO.java
@@ -1,5 +1,7 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import java.math.BigDecimal;
 
@@ -7,9 +9,17 @@ import java.math.BigDecimal;
  * Payment result notification DTO (payment-service -> order-service)
  */
 @Data
+@ApiModel("支付结果通知")
 public class PaymentResultDTO {
+    @ApiModelProperty("订单ID")
     private Long orderId;
-    private String payType;        // FULL / DEPOSIT / BALANCE
+
+    @ApiModelProperty("支付类型: FULL=全款, DEPOSIT=定金, BALANCE=尾款")
+    private String payType;
+
+    @ApiModelProperty("支付金额")
     private BigDecimal paidAmount;
+
+    @ApiModelProperty("微信支付交易号")
     private String transactionIdWx;
 }

`hl-common/src/main/java/com/hulalv/common/dto/RefundResultDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/RefundResultDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/RefundResultDTO.java
index 27b0f25..7483c4e 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/RefundResultDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/RefundResultDTO.java
@@ -1,5 +1,7 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import java.math.BigDecimal;
 
@@ -7,8 +9,14 @@ import java.math.BigDecimal;
  * Refund result notification DTO (payment-service -> order-service)
  */
 @Data
+@ApiModel("退款结果通知")
 public class RefundResultDTO {
+    @ApiModelProperty("订单ID")
     private Long orderId;
+
+    @ApiModelProperty("退款金额")
     private BigDecimal refundAmount;
+
+    @ApiModelProperty("微信退款单号")
     private String refundIdWx;
 }

`hl-common/src/main/java/com/hulalv/common/dto/ResourceDetailDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/ResourceDetailDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/ResourceDetailDTO.java
index 1311d05..3cc83c0 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/ResourceDetailDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/ResourceDetailDTO.java
@@ -1,5 +1,7 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -16,47 +18,48 @@ import java.util.List;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("资源详情")
 public class ResourceDetailDTO {
 
-    /** 资源ID */
+    @ApiModelProperty("资源ID")
     private String resourceId;
 
-    /** 资源类型: SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY */
+    @ApiModelProperty("资源类型: SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY")
     private String resourceType;
 
-    /** 资源名称 */
+    @ApiModelProperty("资源名称")
     private String name;
 
-    /** 副标题 */
+    @ApiModelProperty("副标题")
     private String subtitle;
 
-    /** 简介/描述 */
+    @ApiModelProperty("简介/描述")
     private String description;
 
-    /** 封面图URL */
+    @ApiModelProperty("封面图URL")
     private String cover;
 
-    /** 图片URL列表（轮播图） */
+    @ApiModelProperty("图片URL列表（轮播图）")
     private List<String> images;
 
-    /** 地址 */
+    @ApiModelProperty("地址")
     private String address;
 
-    /** 经度 */
+    @ApiModelProperty("经度")
     private BigDecimal longitude;
 
-    /** 纬度 */
+    @ApiModelProperty("纬度")
     private BigDecimal latitude;
 
-    /** 标签列表 */
+    @ApiModelProperty("标签列表")
     private List<String> tags;
 
-    /** 图文详情（featureIntro JSON） */
+    @ApiModelProperty("图文详情（featureIntro JSON）")
     private String featureIntro;
 
-    /** 评分 */
+    @ApiModelProperty("评分")
     private BigDecimal rating;
 
-    /** 所在城市 */
+    @ApiModelProperty("所在城市")
     private String city;
 }

`hl-common/src/main/java/com/hulalv/common/dto/TravelerValidationDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/TravelerValidationDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/TravelerValidationDTO.java
index 3defc94..f46a8e4 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/TravelerValidationDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/TravelerValidationDTO.java
@@ -1,5 +1,7 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -14,34 +16,23 @@ import java.util.List;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("出行人验证结果")
 public class TravelerValidationDTO {
-    /**
-     * 订单ID
-     */
+    @ApiModelProperty("订单ID")
     private Long orderId;
 
-    /**
-     * 需要的出行人数量
-     */
+    @ApiModelProperty("需要的出行人数量")
     private Integer requiredCount;
 
-    /**
-     * 实际填写的出行人数量
-     */
+    @ApiModelProperty("实际填写的出行人数量")
     private Integer actualCount;
 
-    /**
-     * 是否完整（数量足够且信息完整）
-     */
+    @ApiModelProperty("是否完整（数量足够且信息完整）")
     private Boolean isComplete;
 
-    /**
-     * 信息不完整的出行人ID列表
-     */
+    @ApiModelProperty("信息不完整的出行人ID列表")
     private List<Long> incompleteTravelerIds;
 
-    /**
-     * 验证消息
-     */
+    @ApiModelProperty("验证消息")
     private String message;
 }

`hl-common/src/main/java/com/hulalv/common/dto/WechatDeptSyncDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/WechatDeptSyncDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/WechatDeptSyncDTO.java
index 6eb1bab..13bb274 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/WechatDeptSyncDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/WechatDeptSyncDTO.java
@@ -1,11 +1,21 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("企微部门同步信息")
 public class WechatDeptSyncDTO {
+    @ApiModelProperty("部门ID")
     private Long id;
+
+    @ApiModelProperty("部门名称")
     private String name;
+
+    @ApiModelProperty("上级部门ID")
     private Long parentId;
+
+    @ApiModelProperty("排序值")
     private Integer order;
 }

`hl-common/src/main/java/com/hulalv/common/dto/WechatMessageDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/WechatMessageDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/WechatMessageDTO.java
index 1fae45a..617a3b3 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/WechatMessageDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/WechatMessageDTO.java
@@ -1,12 +1,18 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 import java.io.Serializable;
 import java.util.List;
 
 @Data
+@ApiModel("企微消息推送")
 public class WechatMessageDTO implements Serializable {
+    @ApiModelProperty("接收用户ID列表")
     private List<String> toUserIds;
+
+    @ApiModelProperty("消息内容")
     private String content;
 }

`hl-common/src/main/java/com/hulalv/common/dto/WechatUserSyncDTO.java` (M)

diff --git a/hl-common/src/main/java/com/hulalv/common/dto/WechatUserSyncDTO.java b/hl-common/src/main/java/com/hulalv/common/dto/WechatUserSyncDTO.java
index f047acc..97a07fc 100644
--- a/hl-common/src/main/java/com/hulalv/common/dto/WechatUserSyncDTO.java
+++ b/hl-common/src/main/java/com/hulalv/common/dto/WechatUserSyncDTO.java
@@ -1,16 +1,36 @@
 package com.hulalv.common.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("企微用户同步信息")
 public class WechatUserSyncDTO {
+    @ApiModelProperty("企微用户ID")
     private String userid;
+
+    @ApiModelProperty("用户名称")
     private String name;
+
+    @ApiModelProperty("所属部门ID（逗号分隔）")
     private String department;
+
+    @ApiModelProperty("职位")
     private String position;
+
+    @ApiModelProperty("手机号")
     private String mobile;
+
+    @ApiModelProperty("性别: 1=男, 2=女, 0=未定义")
     private Integer gender;
+
+    @ApiModelProperty("邮箱")
     private String email;
+
+    @ApiModelProperty("头像URL")
     private String avatar;
+
+    @ApiModelProperty("状态: 1=已激活, 2=已禁用, 4=未激活, 5=退出企业")
     private Integer status;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java
index 7adbe0a..93a06f8 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java
@@ -1,9 +1,13 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("分片上传取消请求")
 public class ChunkUploadCancelRequest {
 
+    @ApiModelProperty("上传ID")
     private String uploadId;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java
index 712c15c..d876fcc 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java
@@ -1,9 +1,13 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("分片上传完成请求")
 public class ChunkUploadCompleteRequest {
 
+    @ApiModelProperty("上传ID")
     private String uploadId;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java
index 2d94f04..939a630 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java
@@ -1,13 +1,25 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("分片上传初始化请求")
 public class ChunkUploadInitRequest {
 
+    @ApiModelProperty("文件名")
     private String filename;
+
+    @ApiModelProperty("文件大小(字节)")
     private Long fileSize;
+
+    @ApiModelProperty("文件MIME类型")
     private String contentType;
+
+    @ApiModelProperty("分组标识")
     private String groupKey;
+
+    @ApiModelProperty("文件哈希值")
     private String fileHash;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java
index 96c2499..449c3b4 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,7 +11,9 @@ import java.util.List;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("文件批量ID请求")
 public class FileBatchIdsRequest {
 
+    @ApiModelProperty("文件ID列表")
     private List<Long> fileIds;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java
index bb85acc..1b1d316 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java
@@ -1,9 +1,13 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("文件上传确认请求")
 public class FileUploadConfirmRequest {
 
+    @ApiModelProperty("文件ID")
     private String fileId;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java
index 4d7a140..ee7cd4e 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java
@@ -1,13 +1,25 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("文件上传令牌请求")
 public class FileUploadTokenRequest {
 
+    @ApiModelProperty("文件名")
     private String fileName;
+
+    @ApiModelProperty("文件大小(字节)")
     private Long fileSize;
+
+    @ApiModelProperty("文件哈希值")
     private String fileHash;
+
+    @ApiModelProperty("分组标识")
     private String groupKey;
+
+    @ApiModelProperty("是否强制使用预签名URL")
     private boolean forcePresigned;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java
index 6cd60b6..9f38bc4 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java
@@ -1,12 +1,22 @@
 package com.hulalv.material.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("分片上传初始化结果")
 public class ChunkUploadInitVO {
 
+    @ApiModelProperty("上传ID")
     private String uploadId;
+
+    @ApiModelProperty("分片大小(字节)")
     private int chunkSize;
+
+    @ApiModelProperty("文件ID")
     private String fileId;
+
+    @ApiModelProperty("OSS对象Key")
     private String ossKey;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java
index 1628687..cc0df47 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java
@@ -1,9 +1,13 @@
 package com.hulalv.material.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("分片上传片段结果")
 public class ChunkUploadPartVO {
 
+    @ApiModelProperty("分片ETag标识")
     private String etag;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java
index 779f74d..07b2068 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java
@@ -1,28 +1,58 @@
 package com.hulalv.material.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 import java.time.LocalDateTime;
 
 @Data
+@ApiModel("文件上传令牌结果")
 public class FileUploadTokenVO {
 
+    @ApiModelProperty("文件ID")
     private String fileId;
+
+    @ApiModelProperty("文件MIME类型")
     private String contentType;
+
+    @ApiModelProperty("上传模式")
     private String uploadMode;
+
+    @ApiModelProperty("预签名上传URL")
     private String presignedUrl;
+
+    @ApiModelProperty("OSS对象Key")
     private String ossKey;
+
+    @ApiModelProperty("过期时间")
     private LocalDateTime expireAt;
+
+    @ApiModelProperty("STS临时凭证")
     private StsTokenInfo stsToken;
+
+    @ApiModelProperty("OSS存储桶名称")
     private String bucket;
+
+    @ApiModelProperty("OSS区域")
     private String region;
+
+    @ApiModelProperty("文件信息(秒传时返回)")
     private FileVO file;
 
     @Data
+    @ApiModel("STS临时凭证信息")
     public static class StsTokenInfo {
+        @ApiModelProperty("访问密钥ID")
         private String accessKeyId;
+
+        @ApiModelProperty("访问密钥Secret")
         private String accessKeySecret;
+
+        @ApiModelProperty("安全令牌")
         private String securityToken;
+
+        @ApiModelProperty("过期时间")
         private String expiration;
     }
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java
index a5e43b9..90612e6 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java
@@ -1,23 +1,51 @@
 package com.hulalv.material.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 import java.time.LocalDateTime;
 
 @Data
+@ApiModel("文件信息VO")
 public class FileVO {
 
+    @ApiModelProperty("文件ID")
     private String fileId;
+
+    @ApiModelProperty("文件名")
     private String fileName;
+
+    @ApiModelProperty("文件类型")
     private String fileType;
+
+    @ApiModelProperty("MIME类型")
     private String mimeType;
+
+    @ApiModelProperty("文件大小(字节)")
     private Long fileSize;
+
+    @ApiModelProperty("文件哈希值")
     private String fileHash;
+
+    @ApiModelProperty("OSS访问URL")
     private String ossUrl;
+
+    @ApiModelProperty("缩略图URL")
     private String thumbnailUrl;
+
+    @ApiModelProperty("预览URL")
     private String previewUrl;
+
+    @ApiModelProperty("分组标识")
     private String groupKey;
+
+    @ApiModelProperty("文件状态")
     private String status;
+
+    @ApiModelProperty("引用次数")
     private Integer refCount;
+
+    @ApiModelProperty("创建时间")
     private LocalDateTime createdAt;
 }

`hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java
index 8fb0223..48d0a18 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java
@@ -35,7 +35,7 @@ public class AdminCreateOrderRequest {
     @Min(value = 0)
     private int babyCount = 0;
 
-    @ApiModelProperty(value = "儿童是否需要床位", example = "false")
+    @ApiModelProperty(value = "儿童是否需要床位（影响房间分配和报价计算）", example = "false")
     private Boolean childNeedBed = false;
 
     @ApiModelProperty(value = "团期ID(GROUP产品必填)")
@@ -59,14 +59,14 @@ public class AdminCreateOrderRequest {
     @Size(max = 500, message = "备注不能超过500个字符")
     private String remark;
 
-    @ApiModelProperty(value = "用户手机号（可选，用于关联C端用户）", example = "13800138000")
+    @ApiModelProperty(value = "用户手机号（可选，用于关联C端用户）。如匹配到已注册用户则自动绑定订单", example = "13800138000")
     @Size(max = 20)
     private String userPhone;
 
     @ApiModelProperty(value = "定制师ID（可选，默认为创建人）", example = "1760000000000010")
     private Long customizerId;
 
-    @ApiModelProperty(value = "支付时限（分钟），不传则使用全局默认值", example = "30")
+    @ApiModelProperty(value = "支付时限（分钟），不传则使用全局默认值。超时未支付订单自动取消", example = "30")
     @Min(value = 1, message = "支付时限最少1分钟")
     @Max(value = 1440, message = "支付时限最多1440分钟")
     private Integer expiryMinutes;

`hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java
index dfdbe7d..3eb5db1 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java
@@ -11,11 +11,11 @@ import java.math.BigDecimal;
 @Data
 @ApiModel("管理员退款审批请求")
 public class AdminRefundReviewRequest {
-    @ApiModelProperty(value = "审批结果（APPROVE/REJECT）", required = true, example = "APPROVE")
+    @ApiModelProperty(value = "审批结果：APPROVE=通过（自动调起微信退款）、REJECT=拒绝（用户可发起申诉）", required = true, example = "APPROVE")
     @NotBlank(message = "审批结果不能为空")
     private String action;
 
-    @ApiModelProperty(value = "实际退款金额（审批通过时可调整）", example = "1500.00")
+    @ApiModelProperty(value = "实际退款金额（审批通过时可调整，不传则使用申请金额）。不能超过订单已付金额", example = "1500.00")
     private BigDecimal actualAmount;
 
     @ApiModelProperty(value = "审批备注", example = "同意全额退款")

`hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java
index 2d1c10e..44a424e 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java
@@ -44,7 +44,7 @@ public class AdminUpdateOrderRequest {
     @Min(value = 0, message = "幼童数不能为负")
     private Integer babyCount;
 
-    @ApiModelProperty(value = "商户号", example = "1246532201")
+    @ApiModelProperty(value = "商户号（微信支付商户号，多商户场景使用）", example = "1246532201")
     @Size(max = 32, message = "商户号不能超过32个字符")
     private String mchId;
 
@@ -62,6 +62,6 @@ public class AdminUpdateOrderRequest {
 
     // Note: discount is now managed via separate discount CRUD endpoints (POST/PUT/DELETE /admin/order/{orderId}/discount)
 
-    @ApiModelProperty(value = "出行人列表（如提供则替换全部出行人）")
+    @ApiModelProperty(value = "出行人列表（如提供则替换全部出行人，不传则不修改出行人）")
     private List<CreateOrderRequest.TravelerInfo> travelers;
 }

`hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java
index aeb8c8c..b984863 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java
@@ -13,11 +13,12 @@ public class CreateWorkOrderRequest {
     @NotNull(message = "订单ID不能为空")
     private Long orderId;
 
-    @ApiModelProperty(value = "工单类型: ROOM_CHANGE/ROOM_ADD/CHECKOUT_CHANGE/HOTEL_ISSUE/VEHICLE_CHANGE/SCENIC_ADD/SCENIC_REMOVE/OTHER", required = true)
+    @ApiModelProperty(value = "工单类型: ROOM_CHANGE(换房)/ROOM_ADD(加房)/CHECKOUT_CHANGE(改退房日期)/" +
+            "HOTEL_ISSUE(酒店问题)/VEHICLE_CHANGE(换车)/SCENIC_ADD(加景点)/SCENIC_REMOVE(减景点)/OTHER(其他)", required = true)
     @NotBlank(message = "工单类型不能为空")
     private String type;
 
-    @ApiModelProperty(value = "优先级: URGENT/NORMAL", required = true)
+    @ApiModelProperty(value = "优先级: URGENT(紧急，如当天出发需处理)/NORMAL(普通)", required = true)
     @NotBlank(message = "优先级不能为空")
     private String priority;
 
@@ -31,7 +32,7 @@ public class CreateWorkOrderRequest {
     @ApiModelProperty("资源详情JSON(酒店/车辆/景点信息)")
     private String resourceDetail;
 
-    @ApiModelProperty("差价(正数=加价, 负数=退费)")
+    @ApiModelProperty("差价(正数=客户需补差价, 负数=需退费给客户)")
     private BigDecimal costDifference;
 
     @ApiModelProperty("指定处理人ID")

`hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java
index f2f451c..a678aff 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java
@@ -24,12 +24,12 @@ public class EarlyBirdPlanRequest {
     @NotNull(message = "生效结束日期不能为空")
     private LocalDate endDate;
 
-    @ApiModelProperty(value = "最低人数", required = true, example = "2")
+    @ApiModelProperty(value = "最低出行人数（含成人+儿童），订单人数>=此值才能享受优惠", required = true, example = "2")
     @NotNull(message = "最低人数不能为空")
     @Min(value = 1, message = "最低人数至少为1")
     private Integer minPeople;
 
-    @ApiModelProperty(value = "优惠金额", required = true, example = "200.00")
+    @ApiModelProperty(value = "优惠金额（从订单总价中扣减的固定金额）", required = true, example = "200.00")
     @NotNull(message = "优惠金额不能为空")
     @DecimalMin(value = "0.01", message = "优惠金额必须大于0")
     private BigDecimal discountAmount;

`hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java
index 125cd6a..9a93336 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java
@@ -13,7 +13,7 @@ public class InvoiceApplyRequest {
     @NotNull(message = "orderId is required")
     private Long orderId;
 
-    @ApiModelProperty(value = "抬头类型（personal=个人/company=企业）", example = "personal")
+    @ApiModelProperty(value = "抬头类型：personal=个人（默认）、company=企业（需填写税号）", example = "personal")
     private String titleType = "personal";
 
     @ApiModelProperty(value = "发票抬头", required = true, example = "张三")

`hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java
index 98b28d5..c28453b 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java
@@ -10,7 +10,7 @@ import javax.validation.constraints.Min;
 @Data
 @ApiModel("C端订单查询请求")
 public class MpOrderQueryRequest {
-    @ApiModelProperty(value = "订单状态", example = "PAID")
+    @ApiModelProperty(value = "订单状态（不传则查全部）。可选值：PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/PENDING_BALANCE/PENDING_DEPARTURE/TRAVELLING/COMPLETED/AFTER_SALE/REFUNDING/REFUNDED/CANCELLED", example = "PAID")
     private String status;
 
     @ApiModelProperty(value = "页码", example = "1")

`hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java
index 9782f64..0b13f71 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java
@@ -9,12 +9,12 @@ import java.time.LocalDate;
 import java.util.List;
 
 @Data
-@ApiModel("小程序修改订单请求")
+@ApiModel(value = "小程序修改订单请求", description = "用户可修改出发日期和出行人。修改后系统自动重算价格，内部流程已启动的订单会通知定制师")
 public class MpUpdateOrderRequest {
 
-    @ApiModelProperty(value = "出发日期", example = "2026-05-01")
+    @ApiModelProperty(value = "出发日期（修改出发日期会触发价格重算）", example = "2026-05-01")
     private LocalDate departureDate;
 
-    @ApiModelProperty(value = "出行人列表（如提供则替换全部出行人）")
+    @ApiModelProperty(value = "出行人列表（如提供则替换全部出行人，不传则不修改出行人）")
     private List<CreateOrderRequest.TravelerInfo> travelers;
 }

`hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java
index 4d8aa75..7c32a24 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java
@@ -11,11 +11,11 @@ import javax.validation.constraints.Size;
 @Data
 @ApiModel("退款申请请求")
 public class RefundApplyRequest {
-    @ApiModelProperty(value = "退款类型（字典：refund_type）", required = true, example = "FULL")
+    @ApiModelProperty(value = "退款类型：FULL=全额退款、PARTIAL=部分退款", required = true, example = "FULL")
     @NotBlank(message = "退款类型不能为空")
     private String refundType;
 
-    @ApiModelProperty(value = "退款原因ID", example = "1760000000000001")
+    @ApiModelProperty(value = "退款原因ID（从退款原因列表接口获取）", example = "1760000000000001")
     private Long reasonId;
 
     @ApiModelProperty(value = "退款原因", required = true, example = "行程有变，无法出行")

`hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java
index cb0873c..a6a18a7 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java
@@ -42,12 +42,12 @@ public class RefundPolicyRequest {
     @Data
     @ApiModel("退款规则项")
     public static class RuleItem {
-        @ApiModelProperty(value = "距出发最少天数", required = true, example = "7")
+        @ApiModelProperty(value = "距出发最少天数（含当天）。例如：minDays=7表示出发前7天及以上适用此规则", required = true, example = "7")
         @NotNull(message = "最少天数不能为空")
         @Min(value = 0, message = "最少天数不能小于0")
         private Integer minDays;
 
-        @ApiModelProperty(value = "退款比例（百分比）", required = true, example = "80")
+        @ApiModelProperty(value = "退款比例（百分比，0-100）。例如：80表示退已付金额的80%", required = true, example = "80")
         @NotNull(message = "退款比例不能为空")
         @Min(value = 0, message = "退款比例不能小于0")
         @Max(value = 100, message = "退款比例不能超过100")

`hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java
index f290109..c40fb91 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java
@@ -9,7 +9,10 @@ import javax.validation.constraints.NotBlank;
 @Data
 @ApiModel("更新订单状态请求")
 public class UpdateOrderStatusRequest {
-    @ApiModelProperty(value = "目标状态（字典：order_status）", required = true, example = "CONFIRMED")
+    @ApiModelProperty(value = "目标状态。可选值：PENDING_PAY(待支付)/DEPOSIT_PAID(已付定金)/PAID(已全额支付)/" +
+            "CONFIRMED(已确认)/PENDING_BALANCE(待付尾款)/PENDING_DEPARTURE(待出行)/" +
+            "TRAVELLING(旅行中)/COMPLETED(已完成)/AFTER_SALE(售后中)/REFUNDING(退款中)/" +
+            "REFUNDED(已退款)/CANCELLED(已取消)", required = true, example = "CONFIRMED")
     @NotBlank(message = "状态不能为空")
     private String status;
 }

`hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java b/hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java
index 58106e0..f6bcd64 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java
@@ -82,12 +82,24 @@ public class WorkOrderVO {
     private List<WorkOrderLogVO> logs;
 
     @Data
+    @io.swagger.annotations.ApiModel("工单操作日志VO")
     public static class WorkOrderLogVO {
+        @ApiModelProperty("日志ID")
         private String logId;
+
+        @ApiModelProperty("操作动作")
         private String action;
+
+        @ApiModelProperty("操作动作标签")
         private String actionLabel;
+
+        @ApiModelProperty("操作内容")
         private String content;
+
+        @ApiModelProperty("操作人姓名")
         private String operatorName;
+
+        @ApiModelProperty("操作时间")
         private LocalDateTime createdAt;
     }
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java
index 223810b..84591cf 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java
@@ -9,7 +9,7 @@ import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.Size;
 
 @Data
-@ApiModel("家庭分组保存请求")
+@ApiModel(value = "家庭分组保存请求", description = "仅适用于CUSTOM定制产品，用于将行程按家庭单位分配")
 public class FamilySaveRequest {
 
     @ApiModelProperty(value = "家庭名称", required = true, example = "家庭1")

`hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java
index 4acb045..89b3240 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java
@@ -29,7 +29,8 @@ public class FormulaStepRequest {
     @ApiModelProperty(value = "执行顺序", example = "1")
     private Integer executionOrder;
 
-    @ApiModelProperty(value = "表达式", required = true, example = "baseCost = adultCount * adultUnitCost + childCount * childUnitCost")
+    @ApiModelProperty(value = "Aviator表达式（支持数学运算、条件判断、内置函数；可引用前置步骤的输出变量和公式变量表中的变量）",
+            required = true, example = "baseCost = adultCount * adultUnitCost + childCount * childUnitCost")
     @NotBlank(message = "表达式不能为空")
     @Size(max = 2000, message = "表达式不能超过2000个字符")
     private String expression;

`hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java
index 70e06ec..2cf6432 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java
@@ -8,34 +8,34 @@ import javax.validation.constraints.*;
 import java.time.LocalDate;
 
 @Data
-@ApiModel("create group batch request")
+@ApiModel("创建拼团批次请求")
 public class GroupBatchCreateRequest {
 
-    @ApiModelProperty(value = "batch name", required = true, example = "Jul 20 Batch 1")
-    @NotBlank(message = "batch name required")
+    @ApiModelProperty(value = "批次名称", required = true, example = "7月20日第1批")
+    @NotBlank(message = "批次名称不能为空")
     @Size(max = 128)
     private String batchName;
 
-    @ApiModelProperty(value = "departure date", required = true, example = "2026-07-20")
-    @NotNull(message = "departure date required")
+    @ApiModelProperty(value = "出发日期", required = true, example = "2026-07-20")
+    @NotNull(message = "出发日期不能为空")
     private LocalDate departureDate;
 
-    @ApiModelProperty(value = "enrollment deadline", required = true, example = "2026-07-15")
-    @NotNull(message = "enrollment deadline required")
+    @ApiModelProperty(value = "报名截止日期，必须早于出发日期", required = true, example = "2026-07-15")
+    @NotNull(message = "报名截止日期不能为空")
     private LocalDate enrollmentDeadline;
 
-    @ApiModelProperty(value = "min participants for group confirmation (0=no limit)", example = "10")
+    @ApiModelProperty(value = "最低成团人数（0=不限制，达到此人数自动变为CONFIRMED状态）", example = "10")
     @Min(0)
     private int minParticipants = 0;
 
-    @ApiModelProperty(value = "max participants", required = true, example = "30")
-    @Min(value = 1, message = "max participants must be >= 1")
+    @ApiModelProperty(value = "最大参团人数（报名人数达到上限后自动关闭报名）", required = true, example = "30")
+    @Min(value = 1, message = "最大参团人数至少为1")
     private int maxParticipants;
 
-    @ApiModelProperty(value = "remark", example = "summer special batch")
+    @ApiModelProperty(value = "备注说明", example = "暑期特别批次")
     @Size(max = 512)
     private String remark;
 
-    @ApiModelProperty(value = "sort order", example = "0")
+    @ApiModelProperty(value = "排序序号（越小越靠前）", example = "0")
     private int sortOrder = 0;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java
index 369a7ca..ca769e4 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java
@@ -8,11 +8,11 @@ import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.Size;
 
 @Data
-@ApiModel("disband batch request")
+@ApiModel("解散批次请求")
 public class GroupBatchDisbandRequest {
 
-    @ApiModelProperty(value = "disband reason", required = true, example = "insufficient enrollment")
-    @NotBlank(message = "disband reason required")
+    @ApiModelProperty(value = "解散原因（如：报名人数不足、行程调整等）", required = true, example = "报名人数不足")
+    @NotBlank(message = "解散原因不能为空")
     @Size(max = 512)
     private String reason;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java
index 8c2f4bb..712181e 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java
@@ -9,22 +9,22 @@ import javax.validation.constraints.NotNull;
 import javax.validation.constraints.Size;
 
 @Data
-@ApiModel("batch staff assignment request")
+@ApiModel("批次服务人员分配请求")
 public class GroupBatchStaffRequest {
 
-    @ApiModelProperty(value = "staff ID (from resource-service)", required = true, example = "1760000000000001")
-    @NotNull(message = "staff ID required")
+    @ApiModelProperty(value = "人员ID（来自资源服务的人员库）", required = true, example = "1760000000000001")
+    @NotNull(message = "人员ID不能为空")
     private Long staffId;
 
-    @ApiModelProperty(value = "role in this batch: LEADER/PHOTOGRAPHER/DRIVER/OTHER", required = true, example = "LEADER")
-    @NotBlank(message = "staff role required")
+    @ApiModelProperty(value = "在该批次中的角色：LEADER(领队)/PHOTOGRAPHER(摄影师)/DRIVER(司机)/OTHER(其他)", required = true, example = "LEADER")
+    @NotBlank(message = "人员角色不能为空")
     @Size(max = 32)
     private String staffRole;
 
-    @ApiModelProperty(value = "remark", example = "main guide")
+    @ApiModelProperty(value = "备注（如：主导游、备用摄影师等）", example = "主导游")
     @Size(max = 256)
     private String remark;
 
-    @ApiModelProperty(value = "sort order", example = "0")
+    @ApiModelProperty(value = "排序序号（越小越靠前）", example = "0")
     private int sortOrder = 0;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java
index a8e2de6..4532f60 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java
@@ -9,31 +9,31 @@ import javax.validation.constraints.Size;
 import java.time.LocalDate;
 
 @Data
-@ApiModel("update group batch request")
+@ApiModel("更新拼团批次请求")
 public class GroupBatchUpdateRequest {
 
-    @ApiModelProperty(value = "batch name", example = "Jul 20 Batch 1")
+    @ApiModelProperty(value = "批次名称", example = "7月20日第1批")
     @Size(max = 128)
     private String batchName;
 
-    @ApiModelProperty(value = "departure date", example = "2026-07-20")
+    @ApiModelProperty(value = "出发日期", example = "2026-07-20")
     private LocalDate departureDate;
 
-    @ApiModelProperty(value = "enrollment deadline", example = "2026-07-15")
+    @ApiModelProperty(value = "报名截止日期", example = "2026-07-15")
     private LocalDate enrollmentDeadline;
 
-    @ApiModelProperty(value = "min participants", example = "10")
+    @ApiModelProperty(value = "最低成团人数（0=不限制）", example = "10")
     @Min(0)
     private Integer minParticipants;
 
-    @ApiModelProperty(value = "max participants", example = "30")
+    @ApiModelProperty(value = "最大参团人数（不能低于已报名人数）", example = "30")
     @Min(1)
     private Integer maxParticipants;
 
-    @ApiModelProperty(value = "remark")
+    @ApiModelProperty(value = "备注说明")
     @Size(max = 512)
     private String remark;
 
-    @ApiModelProperty(value = "sort order")
+    @ApiModelProperty(value = "排序序号")
     private Integer sortOrder;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java
index a19ae8a..eae3469 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java
@@ -37,10 +37,10 @@ public class NodeCreateRequest {
     @ApiModelProperty(value = "纬度", example = "26.872108")
     private BigDecimal latitude;
 
-    @ApiModelProperty(value = "关联资源类型：SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE", example = "SCENIC_SPOT")
+    @ApiModelProperty(value = "关联资源类型（关联后可从资源服务获取价格参与成本计算）：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE", example = "SCENIC")
     private String resourceType;
 
-    @ApiModelProperty(value = "关联资源ID", example = "1893012345678901234")
+    @ApiModelProperty(value = "关联资源ID（来自资源服务，关联后节点名称和图片可自动同步）", example = "1893012345678901234")
     private String resourceId;
 
     @ApiModelProperty(value = "节点描述", example = "漫步古城，感受纳西文化")
@@ -58,6 +58,6 @@ public class NodeCreateRequest {
     @ApiModelProperty(value = "数量", example = "1")
     private Integer quantity;
 
-    @ApiModelProperty(value = "所属家庭ID列表（定制产品按家庭分配）")
+    @ApiModelProperty(value = "所属家庭ID列表（仅CUSTOM定制产品使用，实现按家庭分配行程节点）")
     private List<String> familyIds;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java
index a5188da..dacb69c 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java
@@ -28,13 +28,13 @@ public class PriceCalendarRequest {
     @ApiModelProperty(value = "儿童成本价", example = "1800.00")
     private BigDecimal childCostPrice;
 
-    @ApiModelProperty(value = "是否自动计算成本", example = "true")
+    @ApiModelProperty(value = "是否自动计算成本（true时重新测算会自动更新此日期的价格）", example = "true")
     private Boolean costAutoCalc;
 
-    @ApiModelProperty(value = "库存数量", example = "30")
+    @ApiModelProperty(value = "库存数量（CORE/GROUP按人头扣减，CUSTOM/ROUTE按单扣减）", example = "30")
     private Integer stock;
 
-    @ApiModelProperty(value = "状态：OPEN=开放 CLOSED=关闭", example = "OPEN")
+    @ApiModelProperty(value = "状态：OPEN=开放预订 CLOSED=关闭（不可预订）", example = "OPEN")
     private String status;
 
     @ApiModelProperty(value = "备注", example = "五一黄金周特价")

`hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java
index 28b7e49..a937367 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java
@@ -11,10 +11,10 @@ import java.util.List;
 @ApiModel("定价配置请求")
 public class PricingRequest {
 
-    @ApiModelProperty(value = "定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价", example = "AUTO")
+    @ApiModelProperty(value = "定价模式：AUTO=根据行程资源价格自动计算 MANUAL=手动在价格日历设置每日价格 CUSTOM=定制产品整单定价", example = "AUTO")
     private String pricingMode;
 
-    @ApiModelProperty(value = "利润模式：FIXED=固定金额 PERCENT=百分比", example = "FIXED")
+    @ApiModelProperty(value = "利润模式（AUTO模式下生效）：FIXED=在成本基础上加固定金额 PERCENT=在成本基础上按百分比加价", example = "FIXED")
     private String profitMode;
 
     @ApiModelProperty(value = "利润金额（FIXED模式下使用）", example = "500.00")
@@ -32,16 +32,16 @@ public class PricingRequest {
     @ApiModelProperty(value = "餐费预算", example = "100.00")
     private BigDecimal mealBudget;
 
-    @ApiModelProperty(value = "儿童占床价", example = "1800.00")
+    @ApiModelProperty(value = "儿童加床费（childNeedBed=true时额外加收的费用）", example = "1800.00")
     private BigDecimal childWithBed;
 
-    @ApiModelProperty(value = "儿童不占床价", example = "1200.00")
+    @ApiModelProperty(value = "儿童不占床价（暂未使用，预留字段）", example = "1200.00")
     private BigDecimal childNoBed;
 
-    @ApiModelProperty(value = "婴儿价", example = "300.00")
+    @ApiModelProperty(value = "婴儿固定价格（不随日期变化）", example = "300.00")
     private BigDecimal babyPrice;
 
-    @ApiModelProperty(value = "儿童折扣百分比", example = "70.00")
+    @ApiModelProperty(value = "小童折扣百分比（小童价=儿童价×此百分比/100，如70表示打7折）", example = "70.00")
     private BigDecimal childDiscountPercent;
 
     @ApiModelProperty(value = "车型ID列表")
@@ -56,24 +56,24 @@ public class PricingRequest {
     @ApiModelProperty(value = "陪同人员价格", example = "0.00")
     private BigDecimal companionPrice;
 
-    @ApiModelProperty(value = "定制产品总价（CUSTOM模式下使用）", example = "28800.00")
+    @ApiModelProperty(value = "定制产品总价（CUSTOM定价模式下使用，代表整单总价）", example = "28800.00")
     private BigDecimal customTotalPrice;
 
-    @ApiModelProperty(value = "最小成团人数", example = "2")
+    @ApiModelProperty(value = "最小成团人数（CORE/GROUP产品用，影响均摊成本计算）", example = "2")
     private Integer minGroupSize;
 
-    @ApiModelProperty(value = "最大成团人数", example = "16")
+    @ApiModelProperty(value = "最大成团人数（CORE/GROUP产品用）", example = "16")
     private Integer maxGroupSize;
 
-    @ApiModelProperty(value = "支付方式：FULL=全款 DEPOSIT=定金+尾款", example = "FULL")
+    @ApiModelProperty(value = "支付方式：FULL=全款支付 DEPOSIT=定金+尾款分期支付", example = "FULL")
     private String paymentType;
 
-    @ApiModelProperty(value = "定金比例（百分比）", example = "30")
+    @ApiModelProperty(value = "定金比例（百分比，如30代表30%。与depositAmount二选一，优先使用比例）", example = "30")
     private Integer depositRatio;
 
-    @ApiModelProperty(value = "定金金额", example = "1000.00")
+    @ApiModelProperty(value = "定金金额（固定金额，与depositRatio二选一）", example = "1000.00")
     private BigDecimal depositAmount;
 
-    @ApiModelProperty(value = "尾款支付截止天数（出发前N天）", example = "7")
+    @ApiModelProperty(value = "尾款支付截止天数（出发前N天必须支付尾款，超时可能取消订单）", example = "7")
     private Integer balanceDueDays;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java
index 23e1203..99033be 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java
@@ -10,10 +10,11 @@ import javax.validation.constraints.NotBlank;
 @ApiModel("产品状态变更请求")
 public class ProductStatusRequest {
 
-    @ApiModelProperty(value = "目标状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED", required = true, example = "PUBLISHED")
+    @ApiModelProperty(value = "目标状态。核心/小蒙马：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED；定制产品：COMPLETED",
+            required = true, example = "PUBLISHED")
     @NotBlank(message = "目标状态不能为空")
     private String status;
 
-    @ApiModelProperty(value = "状态变更原因（驳回时必填）", example = "行程信息不完整，请补充")
+    @ApiModelProperty(value = "状态变更原因（驳回时必填；上架/下架审批时可填）", example = "行程信息不完整，请补充")
     private String reason;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java
index fd39d97..92c28aa 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java
@@ -21,18 +21,18 @@ public class QuoteRequest {
     @Min(value = 1, message = "成人人数最少1人")
     private Integer adultCount;
 
-    @ApiModelProperty(value = "儿童人数（占床）", example = "1")
+    @ApiModelProperty(value = "儿童人数（占床，按儿童价计算）", example = "1")
     @Min(value = 0, message = "儿童人数不能为负数")
     private Integer childCount = 0;
 
-    @ApiModelProperty(value = "小童人数（不占床）", example = "0")
+    @ApiModelProperty(value = "小童人数（不占床，按儿童价 × childDiscountPercent 折扣比例计算）", example = "0")
     @Min(value = 0, message = "小童人数不能为负数")
     private Integer youngChildCount = 0;
 
-    @ApiModelProperty(value = "婴儿人数", example = "0")
+    @ApiModelProperty(value = "婴儿人数（按固定 babyPrice 计算）", example = "0")
     @Min(value = 0, message = "幼童人数不能为负数")
     private Integer babyCount = 0;
 
-    @ApiModelProperty(value = "儿童是否加床", example = "false")
+    @ApiModelProperty(value = "儿童是否加床（true 时额外加收 childWithBed 费用）", example = "false")
     private Boolean childNeedBed = false;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java
index 46060ff..63b4dc9 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,7 +11,9 @@ import java.util.List;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("批量素材ID请求")
 public class BatchMaterialIdsRequest {
 
+    @ApiModelProperty("素材ID列表")
     private List<Long> materialIds;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java
index e859cea..53c0c3d 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,7 +11,9 @@ import java.util.List;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("批量引用绑定请求")
 public class RefBatchBindRequest {
 
+    @ApiModelProperty("引用绑定列表")
     private List<RefBindRequest> refs;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java
index 965c0e9..b532ee1 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,7 +11,9 @@ import java.util.List;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("批量引用解绑请求")
 public class RefBatchUnbindRequest {
 
+    @ApiModelProperty("引用解绑列表")
     private List<RefUnbindRequest> refs;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java
index 8d95b02..16fdb65 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -7,11 +9,21 @@ import lombok.NoArgsConstructor;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("引用绑定请求")
 public class RefBindRequest {
 
+    @ApiModelProperty("素材ID")
     private Long materialId;
+
+    @ApiModelProperty("业务类型")
     private String bizType;
+
+    @ApiModelProperty("业务ID")
     private Long bizId;
+
+    @ApiModelProperty("业务名称")
     private String bizName;
+
+    @ApiModelProperty("用途类型")
     private String usageType;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java
index 04252db..cdd7901 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -7,10 +9,18 @@ import lombok.NoArgsConstructor;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("引用解绑请求")
 public class RefUnbindRequest {
 
+    @ApiModelProperty("素材ID")
     private Long materialId;
+
+    @ApiModelProperty("业务类型")
     private String bizType;
+
+    @ApiModelProperty("业务ID")
     private Long bizId;
+
+    @ApiModelProperty("用途类型")
     private String usageType;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java
index da0d81d..9188dfb 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -7,7 +9,12 @@ import lombok.NoArgsConstructor;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("资源封面查询")
 public class ResourceCoverQuery {
+
+    @ApiModelProperty("资源类型")
     private String resourceType;
+
+    @ApiModelProperty("资源ID")
     private String resourceId;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java
index 90b98cf..685d2e0 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -12,16 +14,21 @@ import java.util.List;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("资源价格查询")
 public class ResourcePriceQuery {
 
+    @ApiModelProperty("资源ID列表")
     private List<Long> resourceIds;
 
+    @ApiModelProperty("人员类型列表")
     private List<String> staffTypes;
 
+    @ApiModelProperty("开始日期")
     private LocalDate startDate;
 
+    @ApiModelProperty("结束日期")
     private LocalDate endDate;
 
-    /** resource sub-type (e.g. room_type_id for hotel, vehicle category for vehicle) */
+    @ApiModelProperty("资源子类型(如酒店房型ID、车辆类别)")
     private String subType;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java b/hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java
index d072f29..ec5b204 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java
@@ -1,13 +1,25 @@
 package com.hulalv.product.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("素材信息VO")
 public class MaterialVO {
 
+    @ApiModelProperty("素材ID")
     private String materialId;
+
+    @ApiModelProperty("OSS访问URL")
     private String ossUrl;
+
+    @ApiModelProperty("缩略图URL")
     private String thumbnailUrl;
+
+    @ApiModelProperty("素材名称")
     private String materialName;
+
+    @ApiModelProperty("文件类型")
     private String fileType;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java b/hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java
index 4cf6dae..232915a 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -12,15 +14,21 @@ import java.time.LocalDate;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("资源价格VO")
 public class ResourcePriceVO {
 
+    @ApiModelProperty("资源ID")
     private Long resourceId;
 
+    @ApiModelProperty("人员类型")
     private String staffType;
 
+    @ApiModelProperty("日期")
     private LocalDate date;
 
+    @ApiModelProperty("价格")
     private BigDecimal price;
 
+    @ApiModelProperty("资源名称")
     private String resourceName;
 }

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java
index 629213d..23de858 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java
@@ -61,8 +61,8 @@ public class RestaurantCreateRequest {
     @Size(max = 30)
     private String district;
 
-    @ApiModelProperty(value = "城市标签", required = true, example = "拉萨")
-    @NotBlank(message = "城市标签不能为空")
+    @ApiModelProperty(value = "城市名称（纯文本输入）", required = true, example = "拉萨")
+    @NotBlank(message = "城市名称不能为空")
     @Size(max = 30)
     private String cityName;

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java
index 34e331b..ba2f6e9 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java
@@ -25,7 +25,7 @@ public class RestaurantQueryRequest {
     @ApiModelProperty(value = "省份", example = "西藏自治区")
     private String province;
 
-    @ApiModelProperty(value = "城市标签", example = "拉萨")
+    @ApiModelProperty(value = "城市名称筛选（纯文本）", example = "拉萨")
     private String cityName;
 
     @ApiModelProperty(value = "城市", example = "拉萨市")

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java
index 8b62d81..51eb13c 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java
@@ -57,7 +57,7 @@ public class RestaurantUpdateRequest {
     @Size(max = 30)
     private String district;
 
-    @ApiModelProperty(value = "城市标签", example = "拉萨")
+    @ApiModelProperty(value = "城市名称（纯文本输入）", example = "拉萨")
     @Size(max = 30)
     private String cityName;

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java
index df37c80..f0d4d24 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java
@@ -36,7 +36,7 @@ public class RestaurantListVO {
     @ApiModelProperty("人均消费（元）")
     private BigDecimal pricePerPerson;
 
-    @ApiModelProperty("城市标签")
+    @ApiModelProperty("城市名称（纯文本）")
     private String cityName;
 
     @ApiModelProperty("亮点摘要")

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java
index acfd3d8..4396d6e 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java
@@ -54,7 +54,7 @@ public class RestaurantVO {
     @ApiModelProperty("区县")
     private String district;
 
-    @ApiModelProperty("城市标签")
+    @ApiModelProperty("城市名称（纯文本）")
     private String cityName;
 
     @ApiModelProperty("详细地址")

`hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java
index 3dcbbb3..3bde0cd 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java
@@ -6,13 +6,15 @@ import lombok.Data;
 import javax.validation.constraints.NotBlank;
 
 @Data
-@ApiModel("管理员登录请求")
+@ApiModel(value = "管理员登录请求", description = "后台管理员通过用户名+密码登录，新设备首次登录需2FA验证")
 public class AdminLoginRequest {
-    @ApiModelProperty(value = "用户名", required = true, example = "admin")
+    @ApiModelProperty(value = "用户名", required = true, example = "admin",
+            notes = "管理员账号的用户名，由SUPER_ADMIN创建时指定")
     @NotBlank(message = "用户名不能为空")
     private String username;
 
-    @ApiModelProperty(value = "密码", required = true, example = "Admin@2026")
+    @ApiModelProperty(value = "密码", required = true, example = "Admin@2026",
+            notes = "须包含大小写字母和数字，长度8-128位。默认密码为Admin@123456")
     @NotBlank(message = "密码不能为空")
     private String password;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java
index 9c59721..160c8c7 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java
@@ -9,7 +9,7 @@ import javax.validation.constraints.NotBlank;
 @Data
 @ApiModel("联系我们请求")
 public class ContactRequest {
-    @ApiModelProperty(value = "渠道类型：ABOUT=关于我们 ONLINE_CS=在线客服 PHONE=电话咨询", required = true, example = "PHONE")
+    @ApiModelProperty(value = "渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询", required = true, example = "PHONE")
     @NotBlank(message = "渠道类型不能为空")
     private String channelType;
 
@@ -32,6 +32,6 @@ public class ContactRequest {
     @ApiModelProperty(value = "排序号（越小越靠前）", example = "1")
     private Integer sortOrder;
 
-    @ApiModelProperty(value = "状态：0=下线 1=上线", example = "1")
+    @ApiModelProperty(value = "状态，关联字典common_status：0=下线, 1=上线", example = "1")
     private Integer status;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java
index 5d0ffe3..72f20fd 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java
@@ -7,17 +7,20 @@ import javax.validation.constraints.NotBlank;
 import java.util.List;
 
 @Data
-@ApiModel("创建管理员请求")
+@ApiModel(value = "创建管理员请求", description = "创建后台管理员账号，默认密码Admin@123456")
 public class CreateAdminRequest {
-    @ApiModelProperty(value = "用户名", required = true, example = "zhangsan")
+    @ApiModelProperty(value = "用户名", required = true, example = "zhangsan",
+            notes = "全局唯一的登录用户名，创建后不可修改")
     @NotBlank(message = "用户名不能为空")
     private String username;
 
     /** 角色ID列表（多角色），兼容旧的单角色 roleId */
-    @ApiModelProperty(value = "角色ID列表（多角色）", example = "[1,2]")
+    @ApiModelProperty(value = "角色ID列表（多角色）", example = "[1,2]",
+            notes = "支持分配多个角色，管理员登录后可通过切换角色接口切换当前活跃角色")
     private List<Long> roleIds;
 
     /** @deprecated 兼容旧接口，优先使用 roleIds */
-    @ApiModelProperty(value = "角色ID（已废弃，请使用roleIds）", example = "1")
+    @ApiModelProperty(value = "角色ID（已废弃，请使用roleIds）", example = "1",
+            notes = "兼容旧接口的单角色参数，优先使用roleIds")
     private Long roleId;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java
index dff93b6..5d8d05b 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java
@@ -12,18 +12,18 @@ public class CreateJobRequest {
     @NotBlank(message = "任务名称不能为空")
     private String jobName;
 
-    @ApiModelProperty(value = "任务分组", example = "SYSTEM")
+    @ApiModelProperty(value = "任务分组，字典类型：job_group（DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步）", example = "SYSTEM")
     private String jobGroup;
 
-    @ApiModelProperty(value = "调用目标（Bean名称.方法名）", required = true, example = "wechatSyncService.syncDepartments")
+    @ApiModelProperty(value = "调用目标（Bean名称.方法名），方法必须是无参公开方法", required = true, example = "wechatSyncService.syncDepartments")
     @NotBlank(message = "调用目标不能为空")
     private String invokeTarget;
 
-    @ApiModelProperty(value = "Cron表达式", required = true, example = "0 0 2 * * ?")
+    @ApiModelProperty(value = "Cron表达式，标准6位（秒 分 时 日 月 周）", required = true, example = "0 0 2 * * ?")
     @NotBlank(message = "Cron表达式不能为空")
     private String cronExpression;
 
-    @ApiModelProperty(value = "计划执行策略：0=默认 1=立即触发 2=触发一次 3=不触发", example = "0")
+    @ApiModelProperty(value = "计划执行策略，字典类型：job_misfire_policy（DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发）", example = "DEFAULT")
     private String misfirePolicy;
 
     @ApiModelProperty(value = "是否允许并发执行", example = "false")

`hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java
index cbb0455..b7b4fbb 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java
@@ -7,13 +7,15 @@ import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.NotNull;
 
 @Data
-@ApiModel("收藏请求")
+@ApiModel(value = "收藏请求", description = "添加收藏时的请求体，指定收藏的资源类型和ID")
 public class FavoriteRequest {
-    @ApiModelProperty(value = "收藏类型", required = true, example = "SCENIC_SPOT")
+    @ApiModelProperty(value = "收藏类型，关联字典favorite_resource_type", required = true, example = "SCENIC_SPOT",
+            notes = "可选值：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索分类")
     @NotBlank(message = "目标类型不能为空")
     private String targetType;
 
-    @ApiModelProperty(value = "收藏目标ID", required = true, example = "1")
+    @ApiModelProperty(value = "收藏目标ID", required = true, example = "1",
+            notes = "对应资源的ID，如景区ID、活动ID等")
     @NotNull(message = "目标ID不能为空")
     private Long targetId;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java
index 6a9905c..a700a4d 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java
@@ -7,13 +7,15 @@ import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.NotNull;
 
 @Data
-@ApiModel("足迹请求")
+@ApiModel(value = "足迹请求", description = "记录用户浏览足迹时的请求体")
 public class FootprintRequest {
-    @ApiModelProperty(value = "资源类型", required = true, example = "SCENIC_SPOT")
+    @ApiModelProperty(value = "资源类型，关联字典footprint_resource_type", required = true, example = "SCENIC_SPOT",
+            notes = "可选值：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品")
     @NotBlank(message = "资源类型不能为空")
     private String resourceType;
 
-    @ApiModelProperty(value = "资源ID", required = true, example = "1")
+    @ApiModelProperty(value = "资源ID", required = true, example = "1",
+            notes = "对应资源的ID，同一用户同一资源只保留最新一条足迹")
     @NotNull(message = "资源ID不能为空")
     private Long resourceId;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java
index e8ff874..bdc2f40 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java
@@ -6,18 +6,22 @@ import lombok.Data;
 import javax.validation.constraints.NotBlank;
 
 @Data
-@ApiModel("微信小程序登录请求")
+@ApiModel(value = "微信小程序登录请求", description = "通过wx.login获取code进行登录，首次登录自动注册")
 public class LoginRequest {
-    @ApiModelProperty(value = "微信登录授权码", required = true, example = "0c3NKj000...")
+    @ApiModelProperty(value = "微信登录授权码", required = true, example = "0c3NKj000...",
+            notes = "通过wx.login()获取的临时授权码，后端用此code换取openid/unionid")
     @NotBlank(message = "微信code不能为空")
     private String code;
 
-    @ApiModelProperty(value = "手机号授权码（用于获取手机号）", example = "0c3NKj000...")
+    @ApiModelProperty(value = "手机号授权码（用于获取手机号）", example = "0c3NKj000...",
+            notes = "通过getPhoneNumber按钮获取的code，后端用此code换取用户手机号并绑定")
     private String phoneCode;
 
-    @ApiModelProperty(value = "用户头像URL", example = "https://thirdwx.qlogo.cn/xxx")
+    @ApiModelProperty(value = "用户头像URL", example = "https://thirdwx.qlogo.cn/xxx",
+            notes = "微信头像地址，首次登录时传入用于设置用户头像")
     private String avatar;
 
-    @ApiModelProperty(value = "用户昵称", example = "微信用户")
+    @ApiModelProperty(value = "用户昵称", example = "微信用户",
+            notes = "微信昵称，首次登录时传入用于设置用户昵称")
     private String nickname;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java
index 48d700d..945424d 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java
@@ -7,10 +7,11 @@ import lombok.Data;
 import javax.validation.constraints.NotNull;
 
 @Data
-@ApiModel("角色切换请求")
+@ApiModel(value = "角色切换请求", description = "多角色管理员切换当前活跃角色")
 public class SwitchRoleRequest {
 
     @NotNull(message = "角色ID不能为空")
-    @ApiModelProperty(value = "目标角色ID", required = true)
+    @ApiModelProperty(value = "目标角色ID", required = true,
+            notes = "只能切换到当前管理员已分配的角色，切换后返回新Token和对应菜单权限")
     private Long roleId;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java
index f8d33c8..1c67bb6 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java
@@ -15,10 +15,10 @@ public class TravelerRequest {
     @Size(max = 50, message = "姓名长度不能超过50个字符")
     private String name;
 
-    @ApiModelProperty(value = "出行人类型（无需传入，后端根据出生日期自动判断）", hidden = true)
+    @ApiModelProperty(value = "出行人类型，关联字典traveler_type：ADULT=成人, CHILD=儿童, INFANT=婴儿（无需传入，后端根据birthday自动判断）", hidden = true)
     private String travelerType;   // auto-resolved from birthday
 
-    @ApiModelProperty(value = "证件类型：ID_CARD=身份证 PASSPORT=护照", example = "ID_CARD")
+    @ApiModelProperty(value = "证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照", example = "ID_CARD")
     private String idCardType;     // Default: ID_CARD
 
     @ApiModelProperty(value = "证件号码", example = "110101199001011234")
@@ -29,7 +29,7 @@ public class TravelerRequest {
     @Size(max = 20, message = "手机号长度不能超过20个字符")
     private String phone;
 
-    @ApiModelProperty(value = "性别：0=女 1=男", example = "1")
+    @ApiModelProperty(value = "性别，关联字典gender：0=女, 1=男", example = "1")
     private Integer gender;        // 0=female, 1=male
 
     @ApiModelProperty(value = "出生日期（必填，后端根据此字段自动判断人员类型）", required = true, example = "1990-01-01")

`hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java
index 273a9bc..1e4c1f4 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java
@@ -7,13 +7,15 @@ import lombok.Data;
 import javax.validation.constraints.NotBlank;
 
 @Data
-@ApiModel("头像更新请求")
+@ApiModel(value = "头像更新请求", description = "更新管理员头像，需先通过文件服务上传图片")
 public class UpdateAvatarRequest {
 
     @NotBlank(message = "头像URL不能为空")
-    @ApiModelProperty(value = "头像URL", required = true)
+    @ApiModelProperty(value = "头像URL", required = true,
+            notes = "文件服务返回的OSS URL地址")
     private String avatar;
 
-    @ApiModelProperty("文件ID")
+    @ApiModelProperty(value = "文件ID",
+            notes = "文件服务返回的fileId，用于建立文件引用关系，传入后旧头像引用自动解绑")
     private Long fileId;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java
index a42399c..4e85a2a 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java
@@ -10,16 +10,16 @@ public class UpdateJobRequest {
     @ApiModelProperty(value = "任务名称", example = "同步企微通讯录")
     private String jobName;
 
-    @ApiModelProperty(value = "任务分组", example = "SYSTEM")
+    @ApiModelProperty(value = "任务分组，字典类型：job_group（DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步）", example = "SYSTEM")
     private String jobGroup;
 
-    @ApiModelProperty(value = "调用目标（Bean名称.方法名）", example = "wechatSyncService.syncDepartments")
+    @ApiModelProperty(value = "调用目标（Bean名称.方法名），方法必须是无参公开方法", example = "wechatSyncService.syncDepartments")
     private String invokeTarget;
 
-    @ApiModelProperty(value = "Cron表达式", example = "0 0 2 * * ?")
+    @ApiModelProperty(value = "Cron表达式，标准6位（秒 分 时 日 月 周）", example = "0 0 2 * * ?")
     private String cronExpression;
 
-    @ApiModelProperty(value = "计划执行策略：0=默认 1=立即触发 2=触发一次 3=不触发", example = "0")
+    @ApiModelProperty(value = "计划执行策略，字典类型：job_misfire_policy（DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发）", example = "DEFAULT")
     private String misfirePolicy;
 
     @ApiModelProperty(value = "是否允许并发执行", example = "false")

`hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java b/hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java
index 228bb27..2a3ee4f 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.user.notification.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 import javax.validation.constraints.NotBlank;
@@ -10,28 +12,31 @@ import java.util.List;
  * 自定义推送请求
  */
 @Data
+@ApiModel("自定义推送请求")
 public class CustomPushRequest {
 
+    @ApiModelProperty("推送标题")
     @NotBlank(message = "推送标题不能为空")
     private String title;
 
+    @ApiModelProperty("推送内容")
     @NotBlank(message = "推送内容不能为空")
     private String content;
 
-    /** 推送通道: INAPP, SMS, WECHAT_WORK */
+    @ApiModelProperty("推送通道: INAPP/SMS/WECHAT_WORK")
     @NotNull(message = "请选择推送通道")
     private String channel;
 
-    /** 目标类型: ALL_USERS, SPECIFIC_USERS */
+    @ApiModelProperty("目标类型: ALL_USERS/SPECIFIC_USERS")
     @NotNull(message = "请选择目标类型")
     private String targetType;
 
-    /** targetType=SPECIFIC_USERS时必填 */
+    @ApiModelProperty("目标用户ID列表(目标类型为SPECIFIC_USERS时必填)")
     private List<Long> userIds;
 
-    /** 消息分类编码，默认SYSTEM */
+    @ApiModelProperty("消息分类编码，默认SYSTEM")
     private String categoryCode;
 
-    /** 跳转链接（站内信时使用） */
+    @ApiModelProperty("跳转链接(站内信时使用)")
     private String link;
 }

`hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java
index e3cdaf2..495cb3d 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java
@@ -1,19 +1,22 @@
 package com.hulalv.user.notification.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 /**
  * 自定义推送结果
  */
 @Data
+@ApiModel("自定义推送结果VO")
 public class CustomPushResultVO {
 
-    /** 推送总数 */
+    @ApiModelProperty("推送总数")
     private int totalCount;
 
-    /** 成功数 */
+    @ApiModelProperty("成功数")
     private int successCount;
 
-    /** 失败数 */
+    @ApiModelProperty("失败数")
     private int failCount;
 }

`hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java
index 8b7e7d1..7434992 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java
@@ -21,7 +21,7 @@ public class EventConfigVO {
     @ApiModelProperty("所属分类名称")
     private String categoryName;
 
-    @ApiModelProperty("站内信开关")
+    @ApiModelProperty("站内信开关（0=关闭, 1=开启）")
     private Integer inappEnabled;
 
     @ApiModelProperty("站内信标题模板")
@@ -33,7 +33,7 @@ public class EventConfigVO {
     @ApiModelProperty("站内信跳转路径模板")
     private String inappLinkTemplate;
 
-    @ApiModelProperty("短信开关")
+    @ApiModelProperty("短信开关（0=关闭, 1=开启）")
     private Integer smsEnabled;
 
     @ApiModelProperty("阿里云短信模板编号")
@@ -42,7 +42,7 @@ public class EventConfigVO {
     @ApiModelProperty("短信签名")
     private String smsSignName;
 
-    @ApiModelProperty("小程序订阅消息开关")
+    @ApiModelProperty("小程序订阅消息开关（0=关闭, 1=开启）")
     private Integer miniappEnabled;
 
     @ApiModelProperty("微信订阅消息模板ID")
@@ -54,7 +54,7 @@ public class EventConfigVO {
     @ApiModelProperty("小程序字段映射JSON")
     private String miniappFieldMapping;
 
-    @ApiModelProperty("公众号模板消息开关")
+    @ApiModelProperty("公众号模板消息开关（0=关闭, 1=开启）")
     private Integer oaEnabled;
 
     @ApiModelProperty("公众号模板ID")
@@ -66,10 +66,10 @@ public class EventConfigVO {
     @ApiModelProperty("公众号字段映射JSON")
     private String oaFieldMapping;
 
-    @ApiModelProperty("企微通知开关")
+    @ApiModelProperty("企微通知开关（0=关闭, 1=开启）")
     private Integer weworkEnabled;
 
-    @ApiModelProperty("企微接收人类型")
+    @ApiModelProperty("企微接收人类型（ROLE=按角色, DEPT=按部门, SPECIFIC=指定人员）")
     private String weworkReceiverType;
 
     @ApiModelProperty("企微消息内容模板")

`hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java
index 8e44260..52c307c 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java
@@ -14,7 +14,7 @@ public class SendLogVO {
     @ApiModelProperty("事件编码")
     private String eventCode;
 
-    @ApiModelProperty("通道: INAPP/SMS/MINIAPP/OA/WEWORK")
+    @ApiModelProperty("通道，关联字典notification_channel：INAPP=站内信, SMS=短信, MINIAPP=小程序订阅, OA=公众号模板, WEWORK=企业微信")
     private String channel;
 
     @ApiModelProperty("用户ID")
@@ -38,7 +38,7 @@ public class SendLogVO {
     @ApiModelProperty("关联业务类型")
     private String bizType;
 
-    @ApiModelProperty("发送状态: 0成功 1失败 2跳过")
+    @ApiModelProperty("发送状态，关联字典notification_send_status：0=成功, 1=失败, 2=跳过")
     private Integer status;
 
     @ApiModelProperty("失败原因")

`hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java
index 448b5df..9ad4b62 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java
@@ -1,18 +1,25 @@
 package com.hulalv.user.notification.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 /**
  * 用户简要信息（自定义推送选择目标用户时使用）
  */
 @Data
+@ApiModel("用户简要信息VO")
 public class UserSimpleVO {
 
+    @ApiModelProperty("用户ID")
     private Long id;
 
+    @ApiModelProperty("真实姓名")
     private String realName;
 
+    @ApiModelProperty("手机号")
     private String phone;
 
+    @ApiModelProperty("头像URL")
     private String avatarUrl;
 }

`hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java b/hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java
index 8bd3d9d..53a203c 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java
@@ -14,7 +14,7 @@ public class ContactVO {
     @ApiModelProperty(value = "联系方式ID")
     private String id;
 
-    @ApiModelProperty(value = "渠道类型：ABOUT=关于我们 ONLINE_CS=在线客服 PHONE=电话咨询")
+    @ApiModelProperty(value = "渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询")
     private String channelType;
 
     @ApiModelProperty(value = "标题")
@@ -35,7 +35,7 @@ public class ContactVO {
     @ApiModelProperty(value = "排序号")
     private Integer sortOrder;
 
-    @ApiModelProperty(value = "状态：0=下线 1=上线")
+    @ApiModelProperty(value = "状态，关联字典common_status：0=下线, 1=上线")
     private Integer status;
 
     @ApiModelProperty(value = "创建时间")

`hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java b/hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java
index d72a7b3..be9f83a 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java
@@ -26,7 +26,7 @@ public class CustomerVO {
     @ApiModelProperty(value = "手机号（不脱敏）")
     private String phone;
 
-    @ApiModelProperty(value = "状态：ACTIVE=正常 DISABLED=禁用")
+    @ApiModelProperty(value = "状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁")
     private String status;
 
     @ApiModelProperty(value = "创建时间")

`hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java b/hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java
index 89620fe..3582c3d 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java
@@ -18,7 +18,7 @@ public class LoginLogVO {
     @ApiModelProperty(value = "管理员名称")
     private String adminName;
 
-    @ApiModelProperty(value = "登录方式：PASSWORD=密码 WECHAT=企微扫码 TWO_FA=二次验证")
+    @ApiModelProperty(value = "登录方式，关联字典login_method：PASSWORD=密码登录, WECHAT_QR=企微扫码登录, TWO_FA=二次验证登录")
     private String loginMethod;
 
     @ApiModelProperty(value = "登录IP地址")
@@ -36,7 +36,7 @@ public class LoginLogVO {
     @ApiModelProperty(value = "登录地区")
     private String location;
 
-    @ApiModelProperty(value = "登录状态：SUCCESS=成功 FAILED=失败")
+    @ApiModelProperty(value = "登录状态，关联字典login_status：SUCCESS=成功, FAILED=失败")
     private String status;
 
     @ApiModelProperty(value = "失败原因")

`hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java b/hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java
index cb64d33..bbc0ede 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java
@@ -29,20 +29,20 @@ public class UserVO {
     @ApiModelProperty(value = "真实手机号（仅内部接口返回，用于订单预填）", hidden = true)
     private String rawPhone; // 真实手机号（仅内部接口返回，用于订单预填）
 
-    @ApiModelProperty(value = "状态：ACTIVE=正常 DISABLED=禁用")
+    @ApiModelProperty(value = "状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁")
     private String status;
 
     // 个人信息字段(用于编辑"本人"出行人信息)
     @ApiModelProperty(value = "真实姓名")
     private String realName;
 
-    @ApiModelProperty(value = "证件类型：ID_CARD=身份证 PASSPORT=护照")
+    @ApiModelProperty(value = "证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照")
     private String idCardType;
 
     @ApiModelProperty(value = "证件号码")
     private String idCardNo;
 
-    @ApiModelProperty(value = "性别：0=女 1=男")
+    @ApiModelProperty(value = "性别，关联字典gender：0=女, 1=男")
     private Integer gender;
 
     @ApiModelProperty(value = "出生日期")

数据库变更 (SQL)

`sql/add_customer_service_role.sql` (A)

-- 新增客服角色
-- 权限：查看全部订单、全部产品（含定制产品）、配置保险、配置合同、查看素材

-- 1. 创建角色
INSERT INTO sys_role (role_id, role_name, role_key, sort_order, status)
VALUES (8, '客服', 'CUSTOMER_SERVICE', 8, 'ACTIVE');

-- 2. 分配菜单权限
INSERT INTO sys_role_menu (role_id, menu_id) VALUES
-- 订单管理（查看，不含创建）
(8, 700),    -- 订单管理（目录）
(8, 710),    -- 订单列表
(8, 730),    -- 订单详情
(8, 740),    -- 早鸟优惠
(8, 750),    -- 工单管理
-- 退款管理（查看）
(8, 6001),   -- 退款管理（目录）
(8, 6010),   -- 退款申请
(8, 6020),   -- 退款政策
(8, 6030),   -- 退款原因
-- 产品管理（查看全部，含定制产品，不含增删改按钮）
(8, 500),    -- 产品管理（目录）
(8, 510),    -- 产品列表
(8, 520),    -- 产品线管理
(8, 530),    -- 团期管理
-- 保险管理（配置）
(8, 800),    -- 保险管理（目录）
(8, 810),    -- 保险产品
(8, 820),    -- 保险订单
(8, 830),    -- 保险方案
-- 合同管理（配置）
(8, 850),    -- 合同管理（目录）
(8, 851),    -- 合同列表
(8, 852),    -- 补充约定模板
-- 素材库（查看）
(8, 1890000000000000100);  -- 素材库

`sql/dict_data_seed.sql` (M)

diff --git a/sql/dict_data_seed.sql b/sql/dict_data_seed.sql
index b4646bd..933fd27 100644
--- a/sql/dict_data_seed.sql
+++ b/sql/dict_data_seed.sql
@@ -5,7 +5,7 @@
 USE hl_user_service;
 
 -- ============================================================
--- Dict Types (7 types)
+-- Dict Types (9 types)
 -- ============================================================
 INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status, remark, created_at, updated_at)
 VALUES
@@ -15,7 +15,9 @@ VALUES
   (4, '字典分类',     'dict_category',      'BASE', 'ACTIVE', NULL, NOW(), NOW()),
   (5, '任务补偿策略', 'job_misfire_policy',  'BASE', 'ACTIVE', NULL, NOW(), NOW()),
   (6, '部门状态',     'dept_status',         'BASE', 'ACTIVE', NULL, NOW(), NOW()),
-  (7, '任务日志状态', 'job_log_status',      'BASE', 'ACTIVE', NULL, NOW(), NOW());
+  (7, '任务日志状态', 'job_log_status',      'BASE', 'ACTIVE', NULL, NOW(), NOW()),
+  (8, '任务状态',     'job_status',          'BASE', 'ACTIVE', NULL, NOW(), NOW()),
+  (9, '任务分组',     'job_group',           'BASE', 'ACTIVE', NULL, NOW(), NOW());
 
 -- ============================================================
 -- Dict Data (remark stores el-tag type for styling)
@@ -67,4 +69,18 @@ VALUES
   (701, 'job_log_status', '成功', 'SUCCESS', 1, 'ACTIVE', 'success', NOW(), NOW()),
   (702, 'job_log_status', '失败', 'FAIL',    2, 'ACTIVE', 'danger',  NOW(), NOW());
 
+-- job_status
+INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status, remark, created_at, updated_at)
+VALUES
+  (801, 'job_status', '启用',   'ACTIVE', 1, 'ACTIVE', 'success', NOW(), NOW()),
+  (802, 'job_status', '已暂停', 'PAUSED', 2, 'ACTIVE', 'info',    NOW(), NOW());
+
+-- job_group
+INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status, remark, created_at, updated_at)
+VALUES
+  (901, 'job_group', '默认分组', 'DEFAULT',   1, 'ACTIVE', '',        NOW(), NOW()),
+  (902, 'job_group', '系统任务', 'SYSTEM',    2, 'ACTIVE', 'primary', NOW(), NOW()),
+  (903, 'job_group', '企微同步', 'WECHAT',    3, 'ACTIVE', 'success', NOW(), NOW()),
+  (904, 'job_group', '保险同步', 'INSURANCE', 4, 'ACTIVE', 'warning', NOW(), NOW());
+
 SELECT 'Seed complete' AS result;

`sql/dict_fix_frontend.sql` (A)

-- ============================================================
-- 前端缺失的字典类型和字典数据补齐
-- 对比前端 hl-ui 代码 vs 后端 sys_dict_type 表
-- ============================================================

-- 1. cities - 城市（树形字典，MobilePreview/useLocation用）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000001, '城市', 'cities', 'BASE', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1900100001, 'cities', '海拉尔', 'hailar', 1, 'ACTIVE'),
(1900100002, 'cities', '满洲里', 'manzhouli', 2, 'ACTIVE'),
(1900100003, 'cities', '额尔古纳', 'eergu', 3, 'ACTIVE'),
(1900100004, 'cities', '根河', 'genhe', 4, 'ACTIVE'),
(1900100005, 'cities', '牙克石', 'yakeshi', 5, 'ACTIVE'),
(1900100006, 'cities', '扎兰屯', 'zhalantun', 6, 'ACTIVE'),
(1900100007, 'cities', '阿尔山', 'aershan', 7, 'ACTIVE'),
(1900100008, 'cities', '室韦', 'shiwei', 8, 'ACTIVE'),
(1900100009, 'cities', '恩和', 'enhe', 9, 'ACTIVE'),
(1900100010, 'cities', '黑山头', 'heishantou', 10, 'ACTIVE'),
(1900100011, 'cities', '陈巴尔虎旗', 'chenbaerhu', 11, 'ACTIVE'),
(1900100012, 'cities', '新巴尔虎左旗', 'xinbaerhuzuo', 12, 'ACTIVE'),
(1900100013, 'cities', '新巴尔虎右旗', 'xinbaerhuyou', 13, 'ACTIVE'),
(1900100014, 'cities', '鄂温克旗', 'ewenke', 14, 'ACTIVE'),
(1900100015, 'cities', '莫尔道嘎', 'moerdaoga', 15, 'ACTIVE');

-- 2. city - 城市筛选（产品行程资源面板用）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000002, '城市筛选', 'city', 'BASE', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1900200001, 'city', '海拉尔', 'hailar', 1, 'ACTIVE'),
(1900200002, 'city', '满洲里', 'manzhouli', 2, 'ACTIVE'),
(1900200003, 'city', '额尔古纳', 'eergu', 3, 'ACTIVE'),
(1900200004, 'city', '根河', 'genhe', 4, 'ACTIVE'),
(1900200005, 'city', '阿尔山', 'aershan', 5, 'ACTIVE'),
(1900200006, 'city', '室韦', 'shiwei', 6, 'ACTIVE'),
(1900200007, 'city', '恩和', 'enhe', 7, 'ACTIVE'),
(1900200008, 'city', '黑山头', 'heishantou', 8, 'ACTIVE');

-- 3. city_label - 城市标签（餐厅列表筛选用）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000003, '城市标签', 'city_label', 'BASE', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1900300001, 'city_label', '海拉尔', 'hailar', 1, 'ACTIVE'),
(1900300002, 'city_label', '满洲里', 'manzhouli', 2, 'ACTIVE'),
(1900300003, 'city_label', '额尔古纳', 'eergu', 3, 'ACTIVE'),
(1900300004, 'city_label', '根河', 'genhe', 4, 'ACTIVE'),
(1900300005, 'city_label', '阿尔山', 'aershan', 5, 'ACTIVE'),
(1900300006, 'city_label', '室韦', 'shiwei', 6, 'ACTIVE'),
(1900300007, 'city_label', '恩和', 'enhe', 7, 'ACTIVE'),
(1900300008, 'city_label', '黑山头', 'heishantou', 8, 'ACTIVE');

-- 4. environment_type - 环境类型（餐厅编辑用，前端key是environment_type）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000004, '环境类型', 'environment_type', 'BASE', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1900400001, 'environment_type', '室内', 'INDOOR', 1, 'ACTIVE'),
(1900400002, 'environment_type', '户外', 'OUTDOOR', 2, 'ACTIVE'),
(1900400003, 'environment_type', '混合', 'MIXED', 3, 'ACTIVE');

-- 5. cost_unit - 费用计价单位（费用项编辑用）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000005, '费用计价单位', 'cost_unit', 'BUSINESS', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1900500001, 'cost_unit', '元/人', 'PER_PERSON', 1, 'ACTIVE'),
(1900500002, 'cost_unit', '元/台', 'PER_VEHICLE', 2, 'ACTIVE'),
(1900500003, 'cost_unit', '元/天', 'PER_DAY', 3, 'ACTIVE'),
(1900500004, 'cost_unit', '元/次', 'PER_TIME', 4, 'ACTIVE'),
(1900500005, 'cost_unit', '元/间', 'PER_ROOM', 5, 'ACTIVE'),
(1900500006, 'cost_unit', '元/桌', 'PER_TABLE', 6, 'ACTIVE'),
(1900500007, 'cost_unit', '固定金额', 'FIXED', 7, 'ACTIVE');

-- 6. service_unit - 服务计价单位（服务项编辑用）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000006, '服务计价单位', 'service_unit', 'BUSINESS', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1900600001, 'service_unit', '元/人', 'PER_PERSON', 1, 'ACTIVE'),
(1900600002, 'service_unit', '元/次', 'PER_TIME', 2, 'ACTIVE'),
(1900600003, 'service_unit', '元/天', 'PER_DAY', 3, 'ACTIVE'),
(1900600004, 'service_unit', '元/台', 'PER_VEHICLE', 4, 'ACTIVE'),
(1900600005, 'service_unit', '固定金额', 'FIXED', 5, 'ACTIVE');

-- 7. material_tag - 素材标签（素材上传/编辑用）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000007, '素材标签', 'material_tag', 'BUSINESS', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1900700001, 'material_tag', '风景', 'landscape', 1, 'ACTIVE'),
(1900700002, 'material_tag', '人物', 'portrait', 2, 'ACTIVE'),
(1900700003, 'material_tag', '美食', 'food', 3, 'ACTIVE'),
(1900700004, 'material_tag', '住宿', 'hotel', 4, 'ACTIVE'),
(1900700005, 'material_tag', '交通', 'transport', 5, 'ACTIVE'),
(1900700006, 'material_tag', '活动', 'activity', 6, 'ACTIVE'),
(1900700007, 'material_tag', '冬季', 'winter', 7, 'ACTIVE'),
(1900700008, 'material_tag', '夏季', 'summer', 8, 'ACTIVE'),
(1900700009, 'material_tag', '草原', 'grassland', 9, 'ACTIVE'),
(1900700010, 'material_tag', '森林', 'forest', 10, 'ACTIVE');

-- 8. product_category - 产品分类（产品基本信息编辑用）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000008, '产品分类', 'product_category', 'BUSINESS', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1900800001, 'product_category', '亲子游', 'family', 1, 'ACTIVE'),
(1900800002, 'product_category', '蜜月旅行', 'honeymoon', 2, 'ACTIVE'),
(1900800003, 'product_category', '摄影之旅', 'photography', 3, 'ACTIVE'),
(1900800004, 'product_category', '深度体验', 'experience', 4, 'ACTIVE'),
(1900800005, 'product_category', '自驾越野', 'driving', 5, 'ACTIVE');

-- 9. settle_status - 结算状态（结算记录用）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000009, '结算状态', 'settle_status', 'BUSINESS', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1900900001, 'settle_status', '待结算', 'pending', 1, 'ACTIVE'),
(1900900002, 'settle_status', '已结算', 'settled', 2, 'ACTIVE'),
(1900900003, 'settle_status', '结算中', 'processing', 3, 'ACTIVE'),
(1900900004, 'settle_status', '已取消', 'cancelled', 4, 'ACTIVE');

-- 10. trip_status - 行程状态（定制行程列表用）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000010, '行程状态', 'trip_status', 'BUSINESS', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1901000001, 'trip_status', '草稿', 'draft', 1, 'ACTIVE'),
(1901000002, 'trip_status', '已上线', 'online', 2, 'ACTIVE'),
(1901000003, 'trip_status', '已下线', 'offline', 3, 'ACTIVE');

-- 11. trip_type - 行程类型（定制行程表单用）
INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status)
VALUES (1900000011, '行程类型', 'trip_type', 'BUSINESS', 'ACTIVE');

INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status)
VALUES
(1901100001, 'trip_type', '跟团游', 'group', 1, 'ACTIVE'),
(1901100002, 'trip_type', '自由行', 'free', 2, 'ACTIVE'),
(1901100003, 'trip_type', '定制游', 'custom', 3, 'ACTIVE'),
(1901100004, 'trip_type', '半自由行', 'semi_free', 4, 'ACTIVE');

配置变更

`hl-callback-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-callback-service/src/main/resources/bootstrap.yml b/hl-callback-service/src/main/resources/bootstrap.yml
index 7b5d1dc..5d1c2d6 100644
--- a/hl-callback-service/src/main/resources/bootstrap.yml
+++ b/hl-callback-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -13,6 +13,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u4F01\u5FAE\u56DE\u8C03\u670D\u52A1"

`hl-contract-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-contract-service/src/main/resources/bootstrap.yml b/hl-contract-service/src/main/resources/bootstrap.yml
index 2ad048d..9a8fadc 100644
--- a/hl-contract-service/src/main/resources/bootstrap.yml
+++ b/hl-contract-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -17,6 +17,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u5408\u540C\u670D\u52A1"

`hl-file-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-file-service/src/main/resources/bootstrap.yml b/hl-file-service/src/main/resources/bootstrap.yml
index 80be6f4..f060b2f 100644
--- a/hl-file-service/src/main/resources/bootstrap.yml
+++ b/hl-file-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -13,6 +13,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u6587\u4EF6\u670D\u52A1"

`hl-gateway/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-gateway/src/main/resources/bootstrap.yml b/hl-gateway/src/main/resources/bootstrap.yml
index b081310..e4431ac 100644
--- a/hl-gateway/src/main/resources/bootstrap.yml
+++ b/hl-gateway/src/main/resources/bootstrap.yml
@@ -5,10 +5,10 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u7F51\u5173\u670D\u52A1"

`hl-guide-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-guide-service/src/main/resources/bootstrap.yml b/hl-guide-service/src/main/resources/bootstrap.yml
index fe9e45a..e9e3e60 100644
--- a/hl-guide-service/src/main/resources/bootstrap.yml
+++ b/hl-guide-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -17,6 +17,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u653B\u7565\u670D\u52A1"

`hl-insurance-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-insurance-service/src/main/resources/bootstrap.yml b/hl-insurance-service/src/main/resources/bootstrap.yml
index 3fa8071..6a668aa 100644
--- a/hl-insurance-service/src/main/resources/bootstrap.yml
+++ b/hl-insurance-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -17,6 +17,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u4FDD\u9669\u670D\u52A1"

`hl-material-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-material-service/src/main/resources/bootstrap.yml b/hl-material-service/src/main/resources/bootstrap.yml
index a2129ab..affb9da 100644
--- a/hl-material-service/src/main/resources/bootstrap.yml
+++ b/hl-material-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -13,6 +13,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u7D20\u6750\u5E93\u670D\u52A1"

`hl-monitor-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-monitor-service/src/main/resources/bootstrap.yml b/hl-monitor-service/src/main/resources/bootstrap.yml
index d578a0b..32ebbb5 100644
--- a/hl-monitor-service/src/main/resources/bootstrap.yml
+++ b/hl-monitor-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -17,6 +17,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u76D1\u63A7\u670D\u52A1"

`hl-mp-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-mp-service/src/main/resources/bootstrap.yml b/hl-mp-service/src/main/resources/bootstrap.yml
index 826eadd..d3103ee 100644
--- a/hl-mp-service/src/main/resources/bootstrap.yml
+++ b/hl-mp-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -17,6 +17,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u5C0F\u7A0B\u5E8FBFF\u670D\u52A1"

`hl-order-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-order-service/src/main/resources/bootstrap.yml b/hl-order-service/src/main/resources/bootstrap.yml
index 7a5aac5..a5f007a 100644
--- a/hl-order-service/src/main/resources/bootstrap.yml
+++ b/hl-order-service/src/main/resources/bootstrap.yml
@@ -7,7 +7,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -19,6 +19,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u8BA2\u5355\u670D\u52A1"

`hl-payment-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-payment-service/src/main/resources/bootstrap.yml b/hl-payment-service/src/main/resources/bootstrap.yml
index a70de62..00e9efd 100644
--- a/hl-payment-service/src/main/resources/bootstrap.yml
+++ b/hl-payment-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       discovery:
         metadata:
           description: "\u652F\u4ED8\u670D\u52A1"

`hl-product-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-product-service/src/main/resources/bootstrap.yml b/hl-product-service/src/main/resources/bootstrap.yml
index a9fab53..7f26008 100644
--- a/hl-product-service/src/main/resources/bootstrap.yml
+++ b/hl-product-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -17,6 +17,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u4EA7\u54C1\u670D\u52A1"

`hl-resource-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-resource-service/src/main/resources/bootstrap.yml b/hl-resource-service/src/main/resources/bootstrap.yml
index 2f8d63d..05aece0 100644
--- a/hl-resource-service/src/main/resources/bootstrap.yml
+++ b/hl-resource-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -17,6 +17,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u8D44\u6E90\u670D\u52A1"

`hl-review-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-review-service/src/main/resources/bootstrap.yml b/hl-review-service/src/main/resources/bootstrap.yml
index 5a0bc48..4c5260b 100644
--- a/hl-review-service/src/main/resources/bootstrap.yml
+++ b/hl-review-service/src/main/resources/bootstrap.yml
@@ -10,7 +10,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -22,6 +22,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u8BC4\u4EF7\u670D\u52A1"

`hl-task-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-task-service/src/main/resources/bootstrap.yml b/hl-task-service/src/main/resources/bootstrap.yml
index 810de1f..7bc1d67 100644
--- a/hl-task-service/src/main/resources/bootstrap.yml
+++ b/hl-task-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -13,6 +13,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u4EFB\u52A1\u670D\u52A1"

`hl-user-service/src/main/resources/bootstrap.yml` (M)

diff --git a/hl-user-service/src/main/resources/bootstrap.yml b/hl-user-service/src/main/resources/bootstrap.yml
index 520eb90..caedb1f 100644
--- a/hl-user-service/src/main/resources/bootstrap.yml
+++ b/hl-user-service/src/main/resources/bootstrap.yml
@@ -5,7 +5,7 @@ spring:
     active: dev
   cloud:
     nacos:
-      server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+      server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
       config:
         file-extension: yml
         shared-configs:
@@ -13,6 +13,6 @@ spring:
             group: DEFAULT_GROUP
             refresh: true
       discovery:
-        server-addr: ${NACOS_SERVER_ADDR:192.168.100.236:8848}
+        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
         metadata:
           description: "\u7528\u6237\u670D\u52A1"

Service 业务逻辑变更

`hl-callback-service/src/main/java/com/hulalv/callback/config/Knife4jConfig.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/config/Knife4jConfig.java b/hl-callback-service/src/main/java/com/hulalv/callback/config/Knife4jConfig.java
index c64ad00..3fd0b5e 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/config/Knife4jConfig.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/config/Knife4jConfig.java
@@ -1,9 +1,9 @@
 package com.hulalv.callback.config;
 
+import com.google.common.base.Predicate;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
-import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.service.ApiInfo;
 import springfox.documentation.spi.DocumentationType;
@@ -12,6 +12,11 @@ import springfox.documentation.spring.web.plugins.Docket;
 @Configuration
 public class Knife4jConfig {
 
+    /** 排除内部接口和回调接口路径 */
+    private Predicate<String> adminPaths() {
+        return input -> input != null && !input.contains("/internal/") && !input.contains("/callback/");
+    }
+
     @Bean
     public Docket callbackApi() {
         return new Docket(DocumentationType.SWAGGER_2)
@@ -19,7 +24,7 @@ public class Knife4jConfig {
                 .apiInfo(apiInfo())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.callback.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }

`hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java b/hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java
index a9d6ea9..adf49be 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java
@@ -21,7 +21,7 @@ import java.util.concurrent.Executors;
  * 路径: /callback/msg-audit
  */
 @Slf4j
-@Api(tags = "【回调接口】会话内容存档")
+@Api(tags = "【回调接口】会话内容存档", hidden = true)
 @RestController
 @RequestMapping("/callback")
 public class MsgAuditCallbackController {
@@ -59,7 +59,8 @@ public class MsgAuditCallbackController {
      * URL 验证端点。
      * 企业微信配置回调 URL 时发送 GET 请求验证，需解密 echostr 并返回明文。
      */
-    @ApiOperation("会话内容存档回调URL验证")
+    @ApiOperation(value = "会话内容存档回调URL验证",
+            notes = "企业微信会话内容存档的回调URL验证端点。使用独立的Token/AESKey，在企微后台配置会话存档回调URL时进行验证。")
     @GetMapping(value = "/msg-audit", produces = MediaType.TEXT_PLAIN_VALUE)
     public String verifyUrl(
             @RequestParam("msg_signature") String msgSignature,
@@ -89,7 +90,8 @@ public class MsgAuditCallbackController {
      * 企业微信在有新的存档消息时 POST 加密 XML 事件通知。
      * 通知仅表示"有新消息可拉取"，具体消息内容需通过 API 主动拉取。
      */
-    @ApiOperation("接收会话内容存档事件通知")
+    @ApiOperation(value = "接收会话内容存档事件通知",
+            notes = "企业微信在有新的存档消息时推送事件通知到此端点。通知仅表示'有新消息可拉取'，收到后异步触发消息拉取任务（通过Finance SDK API主动拉取具体内容并存储）。必须5秒内返回'success'。")
     @PostMapping(value = "/msg-audit",
             consumes = {MediaType.TEXT_XML_VALUE, MediaType.APPLICATION_XML_VALUE},
             produces = MediaType.TEXT_PLAIN_VALUE)

`hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java b/hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java
index cad043a..0b1d68b 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java
@@ -27,7 +27,7 @@ import java.io.StringReader;
  * No JWT auth required - uses WeChat's own signature verification.
  */
 @Slf4j
-@Api(tags = "【回调接口】企业微信回调")
+@Api(tags = "【回调接口】企业微信回调", hidden = true)
 @RestController
 @RequestMapping("/wx/callback")
 public class WxCallbackController {
@@ -88,7 +88,8 @@ public class WxCallbackController {
      * WeChat sends GET request to verify the callback URL.
      * Must decrypt echostr and return it as plain text.
      */
-    @ApiOperation("Callback URL verification")
+    @ApiOperation(value = "回调URL验证",
+            notes = "企业微信自建应用的回调URL验证端点。企微在配置回调URL时发送GET请求，需解密echostr并返回明文以完成验证。无需JWT认证，使用企微自有的签名校验机制。")
     @GetMapping(value = "/app", produces = MediaType.TEXT_PLAIN_VALUE)
     public String verifyUrl(
             @RequestParam("msg_signature") String msgSignature,
@@ -118,7 +119,8 @@ public class WxCallbackController {
      * WeChat POSTs encrypted XML for all event types.
      * We decrypt, parse, dispatch to handler, and return "success".
      */
-    @ApiOperation("Receive callback events")
+    @ApiOperation(value = "接收回调事件",
+            notes = "企业微信自建应用的事件接收端点。接收加密XML格式的事件通知（审批变更、消息等），解密后按事件类型分发：change_contact→通讯录变更，change_external_contact→外部联系人变更，open_approval_change→审批状态变更。必须5秒内返回'success'。")
     @PostMapping(value = "/app",
             consumes = {MediaType.TEXT_XML_VALUE, MediaType.APPLICATION_XML_VALUE},
             produces = MediaType.TEXT_PLAIN_VALUE)
@@ -162,7 +164,8 @@ public class WxCallbackController {
     // Contact Sync Callback Endpoints
     // ==========================================
 
-    @ApiOperation("Contact sync URL verification")
+    @ApiOperation(value = "联系人同步URL验证",
+            notes = "企业微信通讯录同步的回调URL验证端点。使用独立的Token/AESKey（与应用回调不同），用于接收通讯录变更事件的回调URL配置验证。")
     @GetMapping(value = "/contacts", produces = MediaType.TEXT_PLAIN_VALUE)
     public String verifyContactsUrl(
             @RequestParam("msg_signature") String msgSignature,
@@ -187,7 +190,8 @@ public class WxCallbackController {
         return result;
     }
 
-    @ApiOperation("Receive contact sync events")
+    @ApiOperation(value = "接收联系人同步事件",
+            notes = "企业微信通讯录变更事件接收端点。接收员工创建/更新/删除、部门变更等事件，解密后转发给ContactChangeHandler处理，同步更新本地管理员数据。必须5秒内返回'success'。")
     @PostMapping(value = "/contacts",
             consumes = {MediaType.TEXT_XML_VALUE, MediaType.APPLICATION_XML_VALUE},
             produces = MediaType.TEXT_PLAIN_VALUE)

`hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClient.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClient.java b/hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClient.java
index 127e6f5..e8b0be4 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClient.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClient.java
@@ -11,17 +11,17 @@ import org.springframework.web.bind.annotation.*;
 public interface UserServiceClient {
 
     @PostMapping("/internal/wechat/user/sync")
-    Result<?> syncUser(@RequestBody WechatUserSyncDTO dto);
+    Result<Void> syncUser(@RequestBody WechatUserSyncDTO dto);
 
     @DeleteMapping("/internal/wechat/user/{userid}")
-    Result<?> deleteUser(@PathVariable("userid") String userid);
+    Result<Void> deleteUser(@PathVariable("userid") String userid);
 
     @PostMapping("/internal/wechat/department/sync")
-    Result<?> syncDepartment(@RequestBody WechatDeptSyncDTO dto);
+    Result<Void> syncDepartment(@RequestBody WechatDeptSyncDTO dto);
 
     @DeleteMapping("/internal/wechat/department/{deptId}")
-    Result<?> deleteDepartment(@PathVariable("deptId") Long deptId);
+    Result<Void> deleteDepartment(@PathVariable("deptId") Long deptId);
 
     @PostMapping("/internal/wechat/external-contact/event")
-    Result<?> notifyExternalContactEvent(@RequestBody ExternalContactEventDTO dto);
+    Result<Void> notifyExternalContactEvent(@RequestBody ExternalContactEventDTO dto);
 }

`hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClientFallback.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClientFallback.java b/hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClientFallback.java
index fe9a971..9a8d5e2 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClientFallback.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/feign/UserServiceClientFallback.java
@@ -17,31 +17,31 @@ public class UserServiceClientFallback implements FallbackFactory<UserServiceCli
         log.error("UserServiceClient fallback triggered", cause);
         return new UserServiceClient() {
             @Override
-            public Result<?> syncUser(WechatUserSyncDTO dto) {
+            public Result<Void> syncUser(WechatUserSyncDTO dto) {
                 log.error("Failed to sync user: {}", dto.getUserid());
                 return Result.error(500, "user-service unavailable");
             }
 
             @Override
-            public Result<?> deleteUser(String userid) {
+            public Result<Void> deleteUser(String userid) {
                 log.error("Failed to delete user: {}", userid);
                 return Result.error(500, "user-service unavailable");
             }
 
             @Override
-            public Result<?> syncDepartment(WechatDeptSyncDTO dto) {
+            public Result<Void> syncDepartment(WechatDeptSyncDTO dto) {
                 log.error("Failed to sync department: {}", dto.getId());
                 return Result.error(500, "user-service unavailable");
             }
 
             @Override
-            public Result<?> deleteDepartment(Long deptId) {
+            public Result<Void> deleteDepartment(Long deptId) {
                 log.error("Failed to delete department: {}", deptId);
                 return Result.error(500, "user-service unavailable");
             }
 
             @Override
-            public Result<?> notifyExternalContactEvent(ExternalContactEventDTO dto) {
+            public Result<Void> notifyExternalContactEvent(ExternalContactEventDTO dto) {
                 log.error("Failed to notify external contact event: userId={}, changeType={}",
                         dto.getUserId(), dto.getChangeType());
                 return Result.error(500, "user-service unavailable");

`hl-callback-service/src/main/java/com/hulalv/callback/handler/ApprovalEventHandler.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/handler/ApprovalEventHandler.java b/hl-callback-service/src/main/java/com/hulalv/callback/handler/ApprovalEventHandler.java
index 2f75d43..cd97724 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/handler/ApprovalEventHandler.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/handler/ApprovalEventHandler.java
@@ -117,7 +117,7 @@ public class ApprovalEventHandler {
             // MQ-first for approval log, Feign fallback
             if (!mqLogProducer.sendApprovalLog(dto)) {
                 try {
-                    Result<?> result = monitorFeignClient.pushApprovalLog(dto);
+                    Result<Void> result = monitorFeignClient.pushApprovalLog(dto);
                     if (result.getCode() != 200) {
                         log.error("Feign pushApprovalLog failed: code={}, msg={}",
                                 result.getCode(), result.getMessage());

`hl-callback-service/src/main/java/com/hulalv/callback/handler/ContactChangeHandler.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/handler/ContactChangeHandler.java b/hl-callback-service/src/main/java/com/hulalv/callback/handler/ContactChangeHandler.java
index a288d73..85f2ff0 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/handler/ContactChangeHandler.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/handler/ContactChangeHandler.java
@@ -70,7 +70,7 @@ public class ContactChangeHandler {
         }
 
         log.info("Syncing user via Feign: changeType={}, userid={}", changeType, userid);
-        Result<?> result = userServiceClient.syncUser(dto);
+        Result<Void> result = userServiceClient.syncUser(dto);
         if (result.getCode() != 200) {
             log.error("Feign syncUser failed: code={}, msg={}", result.getCode(), result.getMessage());
         }
@@ -84,7 +84,7 @@ public class ContactChangeHandler {
         }
 
         log.info("Deleting user via Feign: userid={}", userid);
-        Result<?> result = userServiceClient.deleteUser(userid);
+        Result<Void> result = userServiceClient.deleteUser(userid);
         if (result.getCode() != 200) {
             log.error("Feign deleteUser failed: code={}, msg={}", result.getCode(), result.getMessage());
         }
@@ -119,7 +119,7 @@ public class ContactChangeHandler {
         }
 
         log.info("Syncing department via Feign: changeType={}, deptId={}", changeType, dto.getId());
-        Result<?> result = userServiceClient.syncDepartment(dto);
+        Result<Void> result = userServiceClient.syncDepartment(dto);
         if (result.getCode() != 200) {
             log.error("Feign syncDepartment failed: code={}, msg={}", result.getCode(), result.getMessage());
         }
@@ -140,7 +140,7 @@ public class ContactChangeHandler {
             return;
         }
         log.info("Deleting department via Feign: deptId={}", deptId);
-        Result<?> result = userServiceClient.deleteDepartment(deptId);
+        Result<Void> result = userServiceClient.deleteDepartment(deptId);
         if (result.getCode() != 200) {
             log.error("Feign deleteDepartment failed: code={}, msg={}", result.getCode(), result.getMessage());
         }

`hl-callback-service/src/main/java/com/hulalv/callback/handler/ExternalContactHandler.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/handler/ExternalContactHandler.java b/hl-callback-service/src/main/java/com/hulalv/callback/handler/ExternalContactHandler.java
index 9715b66..87f6e0b 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/handler/ExternalContactHandler.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/handler/ExternalContactHandler.java
@@ -55,7 +55,7 @@ public class ExternalContactHandler {
         dto.setExternalUserId(externalUserId);
 
         try {
-            Result<?> result = userServiceClient.notifyExternalContactEvent(dto);
+            Result<Void> result = userServiceClient.notifyExternalContactEvent(dto);
             if (result.getCode() != 200) {
                 log.error("Feign notifyExternalContactEvent failed: code={}, msg={}",
                         result.getCode(), result.getMessage());

`hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/InternalChatMessageController.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/InternalChatMessageController.java b/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/InternalChatMessageController.java
index 36b5a17..88ee4df 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/InternalChatMessageController.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/InternalChatMessageController.java
@@ -27,7 +27,8 @@ public class InternalChatMessageController {
      * @param roomId 群聊ID
      * @param limit 最大条数（默认20，最大50）
      */
-    @ApiOperation("查询指定群的最近消息")
+    @ApiOperation(value = "查询指定群的最近消息",
+            notes = "内部服务间调用。供其他服务通过Feign查询指定群聊的最近消息记录。返回消息基本信息（发送人、时间、类型、内容），不含发送人姓名/头像解析。limit默认20，最大50。")
     @GetMapping("/messages")
     public Result<List<ChatMessageVO>> getRecentMessages(
             @RequestParam String roomId,

`hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/MsgAuditController.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/MsgAuditController.java b/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/MsgAuditController.java
index 57b84e3..9689460 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/MsgAuditController.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/MsgAuditController.java
@@ -29,7 +29,8 @@ public class MsgAuditController {
     private final WechatGroupService wechatGroupService;
     private final ChatMessageService chatMessageService;
 
-    @ApiOperation("获取开启存档的成员列表")
+    @ApiOperation(value = "获取开启存档的成员列表",
+            notes = "调用企微API获取已开启会话内容存档的企业成员列表，返回原始JSON。用于管理员查看哪些成员的聊天记录正在被存档。")
     @GetMapping("/permit-users")
     public Result<JsonNode> getPermitUsers() {
         try {
@@ -41,7 +42,8 @@ public class MsgAuditController {
         }
     }
 
-    @ApiOperation("获取群聊信息")
+    @ApiOperation(value = "获取群聊信息",
+            notes = "通过roomId调用企微API获取企业内部群的群聊信息（群名、群主、成员等），返回原始JSON。外部群无法通过此接口查询。")
     @GetMapping("/group-chat")
     public Result<JsonNode> getGroupChatInfo(
             @ApiParam("群聊ID (roomid)") @RequestParam String roomId) {
@@ -54,7 +56,8 @@ public class MsgAuditController {
         }
     }
 
-    @ApiOperation("检查群聊同意情况")
+    @ApiOperation(value = "检查群聊同意情况",
+            notes = "调用企微API检查指定群聊中各成员是否已同意会话内容存档。未同意的成员其聊天记录不会被存档。返回原始JSON。")
     @GetMapping("/group-chat/agree")
     public Result<JsonNode> checkRoomAgree(
             @ApiParam("群聊ID (roomid)") @RequestParam String roomId) {
@@ -67,7 +70,8 @@ public class MsgAuditController {
         }
     }
 
-    @ApiOperation("拉取聊天记录（需要 Finance SDK）")
+    @ApiOperation(value = "拉取聊天记录（需要 Finance SDK）",
+            notes = "通过Finance SDK拉取会话存档的聊天记录原始数据。需要本地部署Finance SDK动态库。seq为起始序号（0表示从头开始），limit为最大返回条数（上限1000）。返回原始JSON。")
     @GetMapping("/chat-data")
     public Result<JsonNode> getChatData(
             @ApiParam("起始序号（0=从头开始）") @RequestParam(defaultValue = "0") long seq,
@@ -81,7 +85,8 @@ public class MsgAuditController {
         }
     }
 
-    @ApiOperation("获取 SDK 状态")
+    @ApiOperation(value = "获取 SDK 状态",
+            notes = "检查Finance SDK动态库是否可用。可用时支持拉取聊天记录和下载媒体文件；不可用时仅支持HTTP管理API（成员列表、群聊信息等）。")
     @GetMapping("/status")
     public Result<String> getStatus() {
         boolean sdkAvailable = msgAuditService.isSdkAvailable();
@@ -91,14 +96,16 @@ public class MsgAuditController {
         return Result.success(status);
     }
 
-    @ApiOperation("手动触发拉取消息")
+    @ApiOperation(value = "手动触发拉取消息",
+            notes = "手动触发一次消息拉取任务，从上次拉取位置开始拉取新消息并存入数据库。正常情况下由回调事件自动触发，此接口用于手动补拉或调试。返回本次新增的消息数量。")
     @PostMapping("/pull")
     public Result<String> pullMessages() {
         int count = chatMessageService.pullAndStoreMessages();
         return Result.success("拉取完成，新增 " + count + " 条消息");
     }
 
-    @ApiOperation("下载媒体文件（图片、视频等）")
+    @ApiOperation(value = "下载媒体文件（图片、视频等）",
+            notes = "通过Finance SDK下载会话存档中的媒体文件（图片、视频、语音、文件等）。需提供sdkfileid（从聊天记录中获取），可选md5sum用于校验。返回二进制文件流（默认Content-Type为image/jpeg）。需要Finance SDK可用。")
     @GetMapping("/media")
     public ResponseEntity<byte[]> downloadMedia(
             @ApiParam("SDK文件ID") @RequestParam String sdkfileid,
@@ -119,19 +126,22 @@ public class MsgAuditController {
     // 群组管理
     // ==========================================
 
-    @ApiOperation("群组列表")
+    @ApiOperation(value = "群组列表",
+            notes = "获取已添加的企微群组列表。返回所有已录入的群组信息（群名、roomId、群主、成员数、备注等）。群组需先通过'添加群组'接口录入。")
     @GetMapping("/groups")
     public Result<List<WechatGroupVO>> listGroups() {
         return Result.success(wechatGroupService.listGroups());
     }
 
-    @ApiOperation("发现群组（从消息记录中自动发现未添加的群）")
+    @ApiOperation(value = "发现群组（从消息记录中自动发现未添加的群）",
+            notes = "扫描已拉取的聊天消息记录，自动发现尚未录入群组管理的群聊roomId。返回未添加的群列表及基本信息，管理员可据此选择性添加需要监控的群组。")
     @GetMapping("/groups/discover")
     public Result<List<Map<String, Object>>> discoverGroups() {
         return Result.success(wechatGroupService.discoverGroups());
     }
 
-    @ApiOperation("查看群最近消息")
+    @ApiOperation(value = "查看群最近消息",
+            notes = "查询指定群聊的最近消息记录。返回消息列表（含发送人姓名、头像、消息类型、内容、时间等）。limit最大50条。发送人信息通过批量解析userId获取（企微成员显示姓名+头像，外部人员显示userId）。")
     @GetMapping("/groups/messages")
     public Result<List<ChatMessageVO>> getGroupMessages(
             @ApiParam("群聊ID") @RequestParam String roomId,
@@ -162,7 +172,8 @@ public class MsgAuditController {
         return Result.success(voList);
     }
 
-    @ApiOperation("添加群组（输入roomId，自动尝试同步群信息）")
+    @ApiOperation(value = "添加群组（输入roomId，自动尝试同步群信息）",
+            notes = "将指定群聊添加到群组管理列表。自动尝试通过企微API同步群信息（群名、群主、成员等）。内部群可自动获取群信息，外部群需手动填写groupName。可选填写remark备注。")
     @PostMapping("/groups")
     public Result<WechatGroupVO> addGroup(
             @ApiParam("群聊ID") @RequestParam String roomId,
@@ -175,7 +186,8 @@ public class MsgAuditController {
         }
     }
 
-    @ApiOperation("同步群组信息（从企微API刷新）")
+    @ApiOperation(value = "同步群组信息（从企微API刷新）",
+            notes = "从企微API重新拉取指定群组的最新信息（群名、群主、成员列表等）并更新本地记录。仅对内部群有效，外部群无法通过API同步。")
     @PostMapping("/groups/{id}/sync")
     public Result<WechatGroupVO> syncGroup(@PathVariable Long id) {
         try {
@@ -185,7 +197,8 @@ public class MsgAuditController {
         }
     }
 
-    @ApiOperation("更新群组信息（群名、备注）")
+    @ApiOperation(value = "更新群组信息（群名、备注）",
+            notes = "手动修改群组的显示名称和备注信息。适用于外部群（无法自动同步群名）或需要自定义备注的场景。groupName和remark均为可选，传入哪个更新哪个。")
     @PutMapping("/groups/{id}")
     public Result<Void> updateGroup(
             @PathVariable Long id,
@@ -195,7 +208,8 @@ public class MsgAuditController {
         return Result.success(null);
     }
 
-    @ApiOperation("删除群组")
+    @ApiOperation(value = "删除群组",
+            notes = "从群组管理列表中删除指定群组。仅删除本地管理记录，不影响企微实际群聊和已拉取的历史消息数据。")
     @DeleteMapping("/groups/{id}")
     public Result<Void> deleteGroup(@PathVariable Long id) {
         wechatGroupService.deleteGroup(id);

`hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java` (M)

diff --git a/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java b/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java
index cc334e0..001c095 100644
--- a/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java
+++ b/hl-callback-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java
@@ -1,15 +1,33 @@
 package com.hulalv.callback.msgaudit.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("聊天消息VO")
 public class ChatMessageVO {
+    @ApiModelProperty("消息ID")
     private String msgId;
+
+    @ApiModelProperty("发送人ID")
     private String fromUser;
+
+    @ApiModelProperty("发送人姓名")
     private String fromUserName;
+
+    @ApiModelProperty("发送人头像")
     private String fromUserAvatar;
+
+    @ApiModelProperty("群聊ID")
     private String roomId;
+
+    @ApiModelProperty("消息时间戳")
     private Long msgTime;
+
+    @ApiModelProperty("消息类型")
     private String msgType;
+
+    @ApiModelProperty("消息内容")
     private String content;
 }

`hl-contract-service/src/main/java/com/hulalv/contract/config/Knife4jConfig.java` (M)

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/config/Knife4jConfig.java b/hl-contract-service/src/main/java/com/hulalv/contract/config/Knife4jConfig.java
index 9813464..ca855b5 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/config/Knife4jConfig.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/config/Knife4jConfig.java
@@ -1,9 +1,9 @@
 package com.hulalv.contract.config;
 
+import com.google.common.base.Predicate;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
-import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
@@ -11,6 +11,11 @@ import springfox.documentation.spring.web.plugins.Docket;
 @Configuration
 public class Knife4jConfig {
 
+    /** 排除内部接口和回调接口路径 */
+    private Predicate<String> adminPaths() {
+        return input -> input != null && !input.contains("/internal/") && !input.contains("/callback/");
+    }
+
     @Bean
     public Docket contractApi() {
         return new Docket(DocumentationType.SWAGGER_2)
@@ -22,7 +27,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.contract.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 }

`hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java` (M)

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java b/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java
index f955c57..91ac6ed 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java
@@ -21,31 +21,33 @@ public class AdminClauseTemplateController {
 
     private final ClauseTemplateService clauseTemplateService;
 
-    @ApiOperation("获取启用的补充约定模板列表（创建合同用）")
+    @ApiOperation(value = "获取启用的补充约定模板列表（创建合同用）",
+            notes = "返回所有启用状态的补充约定模板，创建合同时选择需要附加的补充约定条款。\n\n**权限**：需管理员登录。")
     @GetMapping("/list")
     public Result<List<ClauseTemplateVO>> listActive() {
         return Result.success(clauseTemplateService.listActive());
     }
 
-    @ApiOperation("获取全部补充约定模板（管理页用）")
+    @ApiOperation(value = "获取全部补充约定模板（管理页用）", notes = "**关联字典**：\n- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用）")
     @GetMapping("/list-all")
     public Result<List<ClauseTemplateVO>> listAll() {
         return Result.success(clauseTemplateService.listAll());
     }
 
-    @ApiOperation("切换模板启用/停用状态")
+    @ApiOperation(value = "切换模板启用/停用状态", notes = "**关联字典**：\n- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用）")
     @PutMapping("/{id}/toggle-status")
     public Result<ClauseTemplateVO> toggleStatus(@ApiParam("模板ID") @PathVariable("id") Long templateId) {
         return Result.success(clauseTemplateService.toggleStatus(templateId));
     }
 
-    @ApiOperation("创建补充约定模板")
+    @ApiOperation(value = "创建补充约定模板", notes = "创建合同补充约定的模板，支持变量占位符。创建后默认启用")
     @PostMapping
     public Result<ClauseTemplateVO> create(@Valid @RequestBody ClauseTemplateRequest request) {
         return Result.success(clauseTemplateService.create(request));
     }
 
-    @ApiOperation("更新补充约定模板")
+    @ApiOperation(value = "更新补充约定模板",
+            notes = "更新模板的标题和内容。已被合同引用的模板更新不影响已创建的合同（合同记录的是快照内容）。\n\n**权限**：需管理员登录。")
     @PutMapping("/{id}")
     public Result<ClauseTemplateVO> update(
             @ApiParam("模板ID") @PathVariable("id") Long templateId,
@@ -53,7 +55,7 @@ public class AdminClauseTemplateController {
         return Result.success(clauseTemplateService.update(templateId, request));
     }
 
-    @ApiOperation("删除补充约定模板")
+    @ApiOperation(value = "删除补充约定模板", notes = "软删除模板。已被合同引用的模板仍可删除，不影响已创建的合同")
     @DeleteMapping("/{id}")
     public Result<Void> delete(@ApiParam("模板ID") @PathVariable("id") Long templateId) {
         clauseTemplateService.delete(templateId);

`hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java` (M)

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java b/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java
index a6a6dbe..437717e 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java
@@ -30,19 +30,20 @@ public class AdminContractController {
 
     private final ContractService contractService;
 
-    @ApiOperation("可用旅行社列表")
+    @ApiOperation(value = "可用旅行社列表", notes = "返回系统配置的旅行社列表，创建合同时选择签约旅行社")
     @GetMapping("/agencies")
     public Result<List<ContractPlatformProperties.AgencyInfo>> listAgencies() {
         return Result.success(contractService.listAgencies());
     }
 
-    @ApiOperation("合同模板列表")
+    @ApiOperation(value = "合同模板列表", notes = "返回合同平台可用的合同模板列表，创建合同时选择模板")
     @GetMapping("/templates")
     public Result<List<ContractTemplateVO>> listTemplates() {
         return Result.success(contractService.listTemplates());
     }
 
-    @ApiOperation("创建合同(标准模式)")
+    @ApiOperation(value = "创建合同(标准模式)", notes = "标准电子签约流程：创建合同 → 平台生成合同PDF → 发送签署短信给出行人 → 出行人在线签署 → 回调更新状态。"
+            + "状态流转：CREATED → SIGNING → SIGNED")
     @PostMapping("/create")
     public Result<ContractDetailVO> createContract(
             @ApiParam("创建合同请求") @Valid @RequestBody CreateContractRequest request,
@@ -51,7 +52,8 @@ public class AdminContractController {
         return Result.success(contractService.createContract(request, adminId));
     }
 
-    @ApiOperation("报备合同(同步模式)")
+    @ApiOperation(value = "报备合同(同步模式)", notes = "线下签约模式：创建合同记录 → 管理员上传已签署的PDF → 同步到12301报备平台。"
+            + "状态流转：CREATED → UPLOADED → REPORTED")
     @PostMapping("/report")
     public Result<ContractDetailVO> reportContract(
             @ApiParam("报备合同请求") @Valid @RequestBody ReportContractRequest request,
@@ -60,49 +62,51 @@ public class AdminContractController {
         return Result.success(contractService.reportContract(request, adminId));
     }
 
-    @ApiOperation("合同列表")
+    @ApiOperation(value = "合同列表", notes = "分页查询合同记录，支持按订单号、合同状态、旅行社筛选\n\n**关联字典**：\n- contract_status：合同状态（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<ContractVO>> listContracts(@ApiParam("合同查询条件") ContractQueryRequest request) {
         return Result.success(contractService.listContracts(request));
     }
 
-    @ApiOperation("合同详情")
+    @ApiOperation(value = "合同详情", notes = "**关联字典**：\n- contract_status：合同状态（显示）")
     @GetMapping("/{id}")
     public Result<ContractDetailVO> getContractDetail(@ApiParam("合同ID") @PathVariable("id") Long contractId) {
         return Result.success(contractService.getContractDetail(contractId));
     }
 
-    @ApiOperation("按订单查询合同")
+    @ApiOperation(value = "按订单查询合同",
+            notes = "查询指定订单下的所有合同记录（含已作废），按创建时间倒序排列。用于订单详情页展示合同历史。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- contract_status：合同状态（列表显示）")
     @GetMapping("/by-order/{orderId}")
     public Result<List<ContractVO>> getByOrder(@ApiParam("订单ID") @PathVariable Long orderId) {
         return Result.success(contractService.getByOrderId(orderId));
     }
 
-    @ApiOperation("获取订单有效合同")
+    @ApiOperation(value = "获取订单有效合同",
+            notes = "返回订单当前有效的合同（非作废状态的最新合同），用于检查订单是否已有签署中或已签署的合同。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- contract_status：合同状态（显示）")
     @GetMapping("/active-by-order/{orderId}")
     public Result<ContractVO> getActiveByOrder(@ApiParam("订单ID") @PathVariable Long orderId) {
         return Result.success(contractService.getActiveContractByOrderId(orderId));
     }
 
-    @ApiOperation("刷新合同状态(从平台同步)")
+    @ApiOperation(value = "刷新合同状态(从平台同步)", notes = "主动查询合同平台的最新签署状态并同步到本地，适用于回调未到达的场景")
     @GetMapping("/{id}/status")
     public Result<ContractVO> refreshStatus(@ApiParam("合同ID") @PathVariable("id") Long contractId) {
         return Result.success(contractService.refreshStatus(contractId));
     }
 
-    @ApiOperation("作废合同")
+    @ApiOperation(value = "作废合同", notes = "将合同标记为作废状态（不可恢复）。作废后该合同不再有效，可重新为订单创建新合同")
     @PostMapping("/{id}/invalidate")
     public Result<ContractVO> invalidateContract(@ApiParam("合同ID") @PathVariable("id") Long contractId) {
         return Result.success(contractService.invalidateContract(contractId));
     }
 
-    @ApiOperation("重发签署短信")
+    @ApiOperation(value = "重发签署短信", notes = "重新发送签署短信给出行人，用于签署短信过期或未收到的场景。仅SIGNING状态的合同可操作")
     @PostMapping("/{id}/resend-sms")
     public Result<Boolean> resendSms(@ApiParam("合同ID") @PathVariable("id") Long contractId) {
         return Result.success(contractService.resendSms(contractId));
     }
 
-    @ApiOperation("上传已签署PDF(同步模式)")
+    @ApiOperation(value = "上传已签署PDF(同步模式)", notes = "同步模式专用：上传线下签署完成的合同PDF文件，上传后合同状态变为UPLOADED，可进一步报备")
     @PostMapping("/{id}/upload-pdf")
     public Result<ContractVO> uploadPdf(
             @ApiParam("合同ID") @PathVariable("id") Long contractId,

`hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java` (M)

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java b/hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java
index 8415d27..bad13a5 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java
@@ -11,7 +11,7 @@ import org.springframework.web.bind.annotation.*;
 
 import javax.validation.Valid;
 
-@Api(tags = "【回调接口】合同回调")
+@Api(tags = "【回调接口】合同回调", hidden = true)
 @Slf4j
 @RestController
 @RequestMapping("/contract/callback")
@@ -20,7 +20,7 @@ public class ContractCallbackController {
 
     private final ContractCallbackService callbackService;
 
-    @ApiOperation("12301合同状态回调")
+    @ApiOperation(value = "12301合同状态回调", notes = "接收12301全国旅游监管平台的合同签署状态回调。出行人签署完成后平台推送状态变更到此接口，自动更新本地合同状态")
     @PostMapping("/12301")
     public ResponseEntity<String> handle12301Callback(@Valid @RequestBody ContractCallbackPayload payload) {
         log.info("Received 12301 callback: contractNumber={}, state={}",

`hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java` (M)

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java b/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java
index 8929f18..3c25a33 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java
@@ -11,7 +11,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "【内部接口】合同（Feign调用）")
+@Api(tags = "【内部接口】合同（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/contract")
 @RequiredArgsConstructor
@@ -19,19 +19,19 @@ public class InternalContractController {
 
     private final ContractService contractService;
 
-    @ApiOperation("按订单查询合同(内部调用)")
+    @ApiOperation(value = "按订单查询合同(内部调用)", notes = "**关联字典**：\n- contract_status：合同状态（返回字段）")
     @GetMapping("/by-order/{orderId}")
     public Result<List<ContractVO>> getByOrder(@PathVariable Long orderId) {
         return Result.success(contractService.getByOrderId(orderId));
     }
 
-    @ApiOperation("按订单批量查询合同(内部调用)")
+    @ApiOperation(value = "按订单批量查询合同(内部调用)", notes = "**关联字典**：\n- contract_status：合同状态（返回字段）")
     @PostMapping("/by-orders")
     public Result<Map<Long, List<ContractVO>>> getByOrders(@RequestBody List<Long> orderIds) {
         return Result.success(contractService.getByOrderIds(orderIds));
     }
 
-    @ApiOperation("检查订单是否有已签署合同(内部调用)")
+    @ApiOperation(value = "检查订单是否有已签署合同(内部调用)", notes = "检查订单是否存在有效签署的合同（SIGNED/REPORTED/UPLOADED状态），用于订单流程中的合同校验")
     @GetMapping("/has-signed/{orderId}")
     public Result<Boolean> hasSigned(@PathVariable Long orderId) {
         List<ContractVO> contracts = contractService.getByOrderId(orderId);
@@ -41,7 +41,7 @@ public class InternalContractController {
         return Result.success(signed);
     }
 
-    @ApiOperation("按订单作废所有有效合同(级联调用)")
+    @ApiOperation(value = "按订单作废所有有效合同(级联调用)", notes = "订单取消或退款时级联作废该订单下所有有效合同，reason参数记录作废原因")
     @PostMapping("/invalidate/{orderId}")
     public Result<Void> invalidateByOrder(@PathVariable Long orderId,
                                            @RequestParam(value = "reason", required = false) String reason) {

`hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java` (M)

diff --git a/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java b/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java
index 90d323c..bbb5883 100644
--- a/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java
+++ b/hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java
@@ -16,7 +16,7 @@ import java.util.Map;
  * C端合同内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "【内部接口】小程序合同（Feign调用）")
+@Api(tags = "【内部接口】小程序合同（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/contract")
 @RequiredArgsConstructor
@@ -24,7 +24,7 @@ public class InternalMpContractController {
 
     private final ContractService contractService;
 
-    @ApiOperation("用户合同列表")
+    @ApiOperation(value = "用户合同列表", notes = "**关联字典**：\n- contract_status：合同状态（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<ContractVO>> listContracts(
             @RequestParam Long userId,
@@ -34,7 +34,7 @@ public class InternalMpContractController {
         return Result.success(contractService.listUserContracts(userId, status, page, pageSize));
     }
 
-    @ApiOperation("用户合同详情")
+    @ApiOperation(value = "用户合同详情", notes = "**关联字典**：\n- contract_status：合同状态（显示）")
     @GetMapping("/{id}")
     public Result<ContractDetailVO> getContractDetail(
             @PathVariable("id") Long contractId,
@@ -42,7 +42,7 @@ public class InternalMpContractController {
         return Result.success(contractService.getUserContractDetail(contractId, userId));
     }
 
-    @ApiOperation("按订单查合同（返回最新有效合同）")
+    @ApiOperation(value = "按订单查合同（返回最新有效合同）", notes = "**关联字典**：\n- contract_status：合同状态（显示）")
     @GetMapping("/by-order/{orderId}")
     public Result<ContractVO> getContractByOrder(
             @PathVariable Long orderId,
@@ -50,7 +50,7 @@ public class InternalMpContractController {
         return Result.success(contractService.getUserContractByOrderId(orderId, userId));
     }
 
-    @ApiOperation("按订单查所有有效合同（TOUR+INSURANCE各一条）")
+    @ApiOperation(value = "按订单查所有有效合同（TOUR+INSURANCE各一条）", notes = "**关联字典**：\n- contract_status：合同状态（显示）")
     @GetMapping("/by-order/{orderId}/all")
     public Result<java.util.List<ContractVO>> getContractsByOrder(
             @PathVariable Long orderId,
@@ -58,7 +58,8 @@ public class InternalMpContractController {
         return Result.success(contractService.getUserContractsByOrderId(orderId, userId));
     }
 
-    @ApiOperation("重新发送合同签署短信")
+    @ApiOperation(value = "重新发送合同签署短信",
+            notes = "内部服务间调用。小程序端用户请求重发签署短信，用于签署链接过期或短信未收到的场景。仅SIGNING状态的合同可操作。\n\n**关联字典**：\n- contract_status：合同状态（仅SIGNING可操作）")
     @PostMapping("/{contractId}/resend-sms")
     public Result<Boolean> resendContractSms(
             @PathVariable("contractId") Long contractId,

`hl-file-service/src/main/java/com/hulalv/file/config/Knife4jConfig.java` (M)

diff --git a/hl-file-service/src/main/java/com/hulalv/file/config/Knife4jConfig.java b/hl-file-service/src/main/java/com/hulalv/file/config/Knife4jConfig.java
index 59a5ded..39f6e7a 100644
--- a/hl-file-service/src/main/java/com/hulalv/file/config/Knife4jConfig.java
+++ b/hl-file-service/src/main/java/com/hulalv/file/config/Knife4jConfig.java
@@ -1,9 +1,9 @@
 package com.hulalv.file.config;
 
+import com.google.common.base.Predicate;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
-import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
@@ -11,6 +11,11 @@ import springfox.documentation.spring.web.plugins.Docket;
 @Configuration
 public class Knife4jConfig {
 
+    /** 排除内部接口和回调接口路径 */
+    private Predicate<String> adminPaths() {
+        return input -> input != null && !input.contains("/internal/") && !input.contains("/callback/");
+    }
+
     @Bean
     public Docket fileApi() {
         return new Docket(DocumentationType.SWAGGER_2)
@@ -22,7 +27,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.file.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 }

`hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java` (M)

diff --git a/hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java b/hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java
index 5b04b02..c78b2d2 100644
--- a/hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java
+++ b/hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java
@@ -33,7 +33,7 @@ public class FileController {
     private final FileService fileService;
     private final FileRefService fileRefService;
 
-    @ApiOperation("请求上传凭证")
+    @ApiOperation(value = "请求上传凭证", notes = "上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求")
     @OperationLog(value = "请求上传凭证", module = "文件管理")
     @PostMapping("/upload/token")
     public Result<UploadTokenVO> requestUploadToken(
@@ -44,7 +44,7 @@ public class FileController {
         return Result.success(vo);
     }
 
-    @ApiOperation("确认上传完成")
+    @ApiOperation(value = "确认上传完成", notes = "上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储")
     @OperationLog(value = "确认上传", module = "文件管理")
     @PostMapping("/upload/confirm")
     public Result<FileVO> confirmUpload(
@@ -55,21 +55,21 @@ public class FileController {
         return Result.success(vo);
     }
 
-    @ApiOperation("文件列表（分页）")
+    @ApiOperation(value = "文件列表（分页）", notes = "支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回\n\n**关联字典**：\n- file_type：文件类型（列表筛选+显示）\n- file_status：文件状态（显示）")
     @GetMapping("/list")
     public Result<IPage<FileVO>> listFiles(@ApiParam("文件查询条件") @Valid FileQueryRequest request) {
         IPage<FileVO> page = fileService.listFiles(request);
         return Result.success(page);
     }
 
-    @ApiOperation("文件详情")
+    @ApiOperation(value = "文件详情", notes = "**关联字典**：\n- file_type：文件类型（显示）\n- file_status：文件状态（显示）")
     @GetMapping("/{fileId}")
     public Result<FileVO> getFileDetail(@ApiParam("文件ID") @PathVariable Long fileId) {
         FileVO vo = fileService.getFileDetail(fileId);
         return Result.success(vo);
     }
 
-    @ApiOperation("删除文件")
+    @ApiOperation(value = "删除文件", notes = "软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理")
     @OperationLog(value = "删除文件", module = "文件管理")
     @DeleteMapping("/{fileId}")
     public Result<Void> deleteFile(@ApiParam("文件ID") @PathVariable Long fileId) {
@@ -77,21 +77,21 @@ public class FileController {
         return Result.success(null);
     }
 
-    @ApiOperation("文件引用列表")
+    @ApiOperation(value = "文件引用列表", notes = "查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除")
     @GetMapping("/{fileId}/refs")
     public Result<List<FileRefVO>> getFileRefs(@ApiParam("文件ID") @PathVariable Long fileId) {
         List<FileRefVO> refs = fileRefService.getRefsByFileId(fileId);
         return Result.success(refs);
     }
 
-    @ApiOperation("存储统计")
+    @ApiOperation(value = "存储统计", notes = "返回文件总数、总存储空间、各类型文件占比等统计信息")
     @GetMapping("/stats")
     public Result<FileStatsVO> getStats() {
         FileStatsVO stats = fileService.getStats();
         return Result.success(stats);
     }
 
-    @ApiOperation("文件内容流式预览")
+    @ApiOperation(value = "文件内容流式预览", notes = "流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件")
     @GetMapping("/{fileId}/preview")
     public void previewContent(@ApiParam("文件ID") @PathVariable Long fileId, HttpServletResponse response) throws IOException {
         fileService.streamContent(fileId, response);

`hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java` (M)

diff --git a/hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java b/hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java
index cf46b6b..3690ff3 100644
--- a/hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java
+++ b/hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java
@@ -30,7 +30,7 @@ import org.springframework.web.multipart.MultipartFile;
 import javax.validation.Valid;
 import java.util.List;
 
-@Api(tags = "【内部接口】文件（Feign调用）")
+@Api(tags = "【内部接口】文件（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/file")
 @RequiredArgsConstructor
@@ -40,28 +40,30 @@ public class InternalFileController {
     private final FileRefService fileRefService;
     private final ChunkUploadService chunkUploadService;
 
-    @ApiOperation("绑定文件到业务实体")
+    @ApiOperation(value = "绑定文件到业务实体", notes = "将文件与业务实体建立引用关系（如景区ID+封面图），同一文件可被多个业务实体引用")
     @PostMapping("/bindRefs")
     public Result<Void> bindRefs(@Valid @RequestBody BindRefsRequest request) {
         fileRefService.bindRefs(request.getBizType(), request.getBizId(), request.getFileIds());
         return Result.success(null);
     }
 
-    @ApiOperation("解绑业务实体的所有文件")
+    @ApiOperation(value = "解绑业务实体的所有文件", notes = "删除指定业务类型+业务ID下的所有文件引用关系，常用于业务实体删除时的级联清理")
     @PostMapping("/unbindRefs")
     public Result<Void> unbindRefs(@Valid @RequestBody UnbindRefsRequest request) {
         fileRefService.unbindRefs(request.getBizType(), request.getBizId());
         return Result.success(null);
     }
 
-    @ApiOperation("批量获取文件信息")
+    @ApiOperation(value = "批量获取文件信息",
+            notes = "内部服务间调用。根据文件ID列表批量查询文件信息（含OSS URL、文件名、类型等），用于其他服务获取关联文件的详细数据。")
     @PostMapping("/byIds")
     public Result<List<FileVO>> getFilesByIds(@Valid @RequestBody BatchFileRequest request) {
         List<FileVO> files = fileService.getFilesByIds(request.getFileIds());
         return Result.success(files);
     }
 
-    @ApiOperation("内部上传凭证（素材服务调用）")
+    @ApiOperation(value = "内部上传凭证（素材服务调用）",
+            notes = "内部服务间调用。素材服务代理调用，为指定管理员生成OSS上传预签名URL和临时凭证，用于素材库的文件上传流程。")
     @PostMapping("/upload/token")
     public Result<UploadTokenVO> requestUploadTokenInternal(
             @Valid @RequestBody UploadTokenRequest request,
@@ -69,7 +71,7 @@ public class InternalFileController {
         return Result.success(fileService.requestUploadToken(request, adminId));
     }
 
-    @ApiOperation("内部直接上传文件（服务间调用）")
+    @ApiOperation(value = "内部直接上传文件（服务间调用）", notes = "服务间直接上传文件到OSS，跳过预签名流程。返回OSS公开访问URL，适用于后端生成的文件（如路线地图截图）")
     @PostMapping("/upload/direct")
     public Result<String> uploadDirect(
             @RequestParam("file") MultipartFile file,
@@ -78,7 +80,8 @@ public class InternalFileController {
         return Result.success(vo.getOssUrl());
     }
 
-    @ApiOperation("内部确认上传（素材服务调用）")
+    @ApiOperation(value = "内部确认上传（素材服务调用）",
+            notes = "内部服务间调用。素材服务代理调用，确认文件已上传至OSS并创建文件记录。支持MD5去重。")
     @PostMapping("/upload/confirm")
     public Result<FileVO> confirmUploadInternal(
             @Valid @RequestBody UploadConfirmRequest request,
@@ -88,7 +91,7 @@ public class InternalFileController {
 
     // ==================== 分片上传 ====================
 
-    @ApiOperation("分片上传-初始化")
+    @ApiOperation(value = "分片上传-初始化", notes = "大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用complete接口合并")
     @PostMapping("/upload/chunk/init")
     public Result<ChunkUploadInitVO> chunkUploadInit(
             @Valid @RequestBody ChunkUploadInitRequest request,
@@ -96,7 +99,7 @@ public class InternalFileController {
         return Result.success(chunkUploadService.initChunkUpload(request, adminId));
     }
 
-    @ApiOperation("分片上传-上传分片")
+    @ApiOperation(value = "分片上传-上传分片", notes = "大文件上传第二步：逐个上传分片，返回分片的ETag用于后续合并校验。支持断点续传，已上传的分片无需重传")
     @PostMapping("/upload/chunk")
     public Result<ChunkUploadPartVO> chunkUploadPart(
             @RequestParam("uploadId") String uploadId,
@@ -105,14 +108,14 @@ public class InternalFileController {
         return Result.success(chunkUploadService.uploadChunk(uploadId, chunkIndex, chunk));
     }
 
-    @ApiOperation("分片上传-完成合并")
+    @ApiOperation(value = "分片上传-完成合并", notes = "大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建文件记录")
     @PostMapping("/upload/chunk/complete")
     public Result<FileVO> chunkUploadComplete(
             @Valid @RequestBody ChunkUploadCompleteRequest request) {
         return Result.success(chunkUploadService.completeChunkUpload(request.getUploadId()));
     }
 
-    @ApiOperation("分片上传-取消")
+    @ApiOperation(value = "分片上传-取消", notes = "取消分片上传任务，清理已上传的分片数据和OSS临时文件")
     @PostMapping("/upload/chunk/cancel")
     public Result<Void> chunkUploadCancel(
             @Valid @RequestBody ChunkUploadCancelRequest request) {

`hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java` (M)

diff --git a/hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java b/hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java
index b78e094..73b8a70 100644
--- a/hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java
+++ b/hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java
@@ -23,7 +23,7 @@ public class MpFileController {
 
     private final FileService fileService;
 
-    @ApiOperation("上传文件（C端用户）")
+    @ApiOperation(value = "上传文件（C端用户）", notes = "小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar")
     @PostMapping("/upload")
     public Result<FileVO> upload(
             @ApiParam("上传文件") @RequestParam("file") MultipartFile file,
@@ -34,7 +34,8 @@ public class MpFileController {
         return Result.success(vo);
     }
 
-    @ApiOperation("文件内容流式预览")
+    @ApiOperation(value = "文件内容流式预览",
+            notes = "流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。")
     @GetMapping("/{fileId}/preview")
     public void previewContent(@ApiParam("文件ID") @PathVariable Long fileId, HttpServletResponse response) throws IOException {
         fileService.streamContent(fileId, response);

`hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java` (M)

diff --git a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java
index a96b208..10fe073 100644
--- a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java
+++ b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java
@@ -22,19 +22,20 @@ public class AdminGuideArticleController {
 
     private final GuideArticleService articleService;
 
-    @ApiOperation("文章列表")
+    @ApiOperation(value = "文章列表", notes = "分页查询攻略文章，支持按分类、状态、关键词筛选\n\n**关联字典**：\n- wiki_status：文章状态（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<GuideArticleListVO>> listArticles(@Valid ArticleQueryRequest query) {
         return Result.success(articleService.listArticles(query));
     }
 
-    @ApiOperation("文章详情")
+    @ApiOperation(value = "文章详情", notes = "**关联字典**：\n- wiki_status：文章状态（显示）")
     @GetMapping("/{articleId}")
     public Result<GuideArticleVO> getArticle(@PathVariable Long articleId) {
         return Result.success(articleService.getArticle(articleId));
     }
 
-    @ApiOperation("创建文章")
+    @ApiOperation(value = "创建文章",
+            notes = "创建攻略文章，需指定分类。创建后默认为草稿状态，需手动发布后小程序端才可见。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- wiki_status：文章状态（创建后默认DRAFT）")
     @PostMapping
     public Result<GuideArticleVO> createArticle(
             @Valid @RequestBody ArticleCreateRequest request,
@@ -43,7 +44,8 @@ public class AdminGuideArticleController {
         return Result.success(articleService.createArticle(request, adminId));
     }
 
-    @ApiOperation("更新文章")
+    @ApiOperation(value = "更新文章",
+            notes = "更新攻略文章的标题、内容、封面图、分类等信息。已发布的文章更新后立即生效。\n\n**权限**：需管理员登录。")
     @PutMapping("/{articleId}")
     public Result<GuideArticleVO> updateArticle(
             @PathVariable Long articleId,
@@ -51,14 +53,15 @@ public class AdminGuideArticleController {
         return Result.success(articleService.updateArticle(articleId, request));
     }
 
-    @ApiOperation("删除文章")
+    @ApiOperation(value = "删除文章",
+            notes = "软删除攻略文章，同时清除文章的标签关联。\n\n**权限**：需管理员登录。")
     @DeleteMapping("/{articleId}")
     public Result<Void> deleteArticle(@PathVariable Long articleId) {
         articleService.deleteArticle(articleId);
         return Result.success();
     }
 
-    @ApiOperation("发布/下架")
+    @ApiOperation(value = "发布/下架", notes = "切换文章发布状态。发布后小程序端可见，下架后小程序端不再展示但管理端仍可查看\n\n**关联字典**：\n- wiki_status：文章状态（状态切换）")
     @PutMapping("/{articleId}/status")
     public Result<Void> updateStatus(
             @PathVariable Long articleId,
@@ -67,7 +70,7 @@ public class AdminGuideArticleController {
         return Result.success();
     }
 
-    @ApiOperation("设置推荐")
+    @ApiOperation(value = "设置推荐", notes = "设置/取消文章推荐。推荐文章会在小程序首页和推荐列表中优先展示")
     @PutMapping("/{articleId}/recommend")
     public Result<Void> updateRecommend(
             @PathVariable Long articleId,
@@ -76,7 +79,7 @@ public class AdminGuideArticleController {
         return Result.success();
     }
 
-    @ApiOperation("设置置顶")
+    @ApiOperation(value = "设置置顶", notes = "设置/取消文章置顶。置顶文章在分类列表中始终排在最前面")
     @PutMapping("/{articleId}/top")
     public Result<Void> updateTop(
             @PathVariable Long articleId,

`hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java` (M)

diff --git a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java
index 8b849da..0eddd64 100644
--- a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java
+++ b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java
@@ -24,19 +24,20 @@ public class AdminGuideCategoryController {
 
     private final GuideCategoryService categoryService;
 
-    @ApiOperation("分类列表")
+    @ApiOperation(value = "分类列表", notes = "返回全部攻略分类（含启用和停用），按排序值升序排列\n\n**关联字典**：\n- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用）")
     @GetMapping("/list")
     public Result<List<GuideCategoryVO>> listCategories() {
         return Result.success(categoryService.listCategories());
     }
 
-    @ApiOperation("启用的分类列表")
+    @ApiOperation(value = "启用的分类列表", notes = "仅返回状态为启用的分类，创建文章时用于选择分类")
     @GetMapping("/enabled")
     public Result<List<GuideCategoryVO>> listEnabledCategories() {
         return Result.success(categoryService.listEnabledCategories());
     }
 
-    @ApiOperation("创建分类")
+    @ApiOperation(value = "创建分类",
+            notes = "创建攻略分类，分类名称不可重复。创建后默认启用，排序值越小越靠前。\n\n**权限**：需管理员登录。")
     @PostMapping
     public Result<GuideCategoryVO> createCategory(
             @Valid @RequestBody CategoryCreateRequest request,
@@ -45,7 +46,8 @@ public class AdminGuideCategoryController {
         return Result.success(categoryService.createCategory(request, adminId));
     }
 
-    @ApiOperation("更新分类")
+    @ApiOperation(value = "更新分类",
+            notes = "更新攻略分类的名称、图标、描述等信息。\n\n**权限**：需管理员登录。")
     @PutMapping("/{categoryId}")
     public Result<GuideCategoryVO> updateCategory(
             @PathVariable Long categoryId,
@@ -53,14 +55,14 @@ public class AdminGuideCategoryController {
         return Result.success(categoryService.updateCategory(categoryId, request));
     }
 
-    @ApiOperation("删除分类")
+    @ApiOperation(value = "删除分类", notes = "删除分类前需确保分类下无文章，否则删除失败")
     @DeleteMapping("/{categoryId}")
     public Result<Void> deleteCategory(@PathVariable Long categoryId) {
         categoryService.deleteCategory(categoryId);
         return Result.success();
     }
 
-    @ApiOperation("更新分类状态")
+    @ApiOperation(value = "更新分类状态", notes = "启用或停用分类。停用后该分类下的文章不会在小程序端展示，但不影响已有文章\n\n**关联字典**：\n- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用）")
     @PutMapping("/{categoryId}/status")
     public Result<Void> updateStatus(
             @PathVariable Long categoryId,
@@ -69,7 +71,8 @@ public class AdminGuideCategoryController {
         return Result.success();
     }
 
-    @ApiOperation("更新分类排序")
+    @ApiOperation(value = "更新分类排序",
+            notes = "更新分类的排序值，排序值越小越靠前。影响小程序端分类导航的展示顺序。\n\n**权限**：需管理员登录。")
     @PutMapping("/{categoryId}/sort")
     public Result<Void> updateSort(
             @PathVariable Long categoryId,

`hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java` (M)

diff --git a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java
index acd32b1..d747ae4 100644
--- a/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java
+++ b/hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java
@@ -23,19 +23,20 @@ public class AdminGuideTagController {
 
     private final GuideTagService tagService;
 
-    @ApiOperation("系统标签列表")
+    @ApiOperation(value = "系统标签列表", notes = "返回管理员创建的系统标签（不含用户自定义标签），用于标签管理页")
     @GetMapping("/managed")
     public Result<List<GuideTagVO>> listManagedTags() {
         return Result.success(tagService.listManagedTags());
     }
 
-    @ApiOperation("所有标签列表")
+    @ApiOperation(value = "所有标签列表", notes = "返回全部标签（含系统标签和用户自定义标签），用于文章编辑时的标签选择器")
     @GetMapping("/all")
     public Result<List<GuideTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建标签")
+    @ApiOperation(value = "创建标签",
+            notes = "创建攻略系统标签，标签名称不可重复。创建后可用于文章分类和筛选。\n\n**权限**：需管理员登录。")
     @PostMapping
     public Result<GuideTagVO> createTag(
             @Valid @RequestBody TagCreateRequest request,
@@ -44,7 +45,8 @@ public class AdminGuideTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("更新标签")
+    @ApiOperation(value = "更新标签",
+            notes = "更新标签名称。标签名称不可与其他已有标签重复。\n\n**权限**：需管理员登录。")
     @PutMapping("/{tagId}")
     public Result<GuideTagVO> updateTag(
             @PathVariable Long tagId,
@@ -52,14 +54,15 @@ public class AdminGuideTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签",
+            notes = "删除标签并自动解除与所有文章的关联关系。\n\n**权限**：需管理员登录。")
     @DeleteMapping("/{tagId}")
     public Result<Void> deleteTag(@PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("更新文章标签")
+    @ApiOperation(value = "更新文章标签", notes = "全量替换文章的标签关联，传入新的标签ID列表（空数组表示清除所有标签）")
     @PutMapping("/article/{articleId}")
     public Result<Void> updateArticleTags(
             @PathVariable Long articleId,

`hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java` (M)

diff --git a/hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java b/hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java
index 42c16dd..62838a6 100644
--- a/hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java
+++ b/hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java
@@ -16,7 +16,7 @@ import java.util.Map;
 /**
  * 内部接口 - 供 mp-service Feign 调用
  */
-@Api(tags = "【内部接口】攻略百科（Feign调用）")
+@Api(tags = "【内部接口】攻略百科（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/wiki")
 @RequiredArgsConstructor
@@ -25,13 +25,14 @@ public class InternalWikiController {
     private final GuideCategoryService categoryService;
     private final GuideArticleService articleService;
 
-    @ApiOperation("查询已启用的攻略分类列表")
+    @ApiOperation(value = "查询已启用的攻略分类列表",
+            notes = "内部服务间调用。返回所有状态为启用的攻略分类，供小程序端展示分类导航。\n\n**关联字典**：\n- common_status：通用状态（仅返回ACTIVE状态的分类）")
     @GetMapping("/categories")
     public Result<List<GuideCategoryVO>> listEnabledCategories() {
         return Result.success(categoryService.listEnabledCategories());
     }
 
-    @ApiOperation("分页查询指定分类下的已发布文章")
+    @ApiOperation(value = "分页查询指定分类下的已发布文章", notes = "**关联字典**：\n- wiki_status：文章状态（返回字段）")
     @GetMapping("/category/{categoryId}/articles")
     public Result<PageResult<Map<String, Object>>> listCategoryArticles(
             @PathVariable Long categoryId,
@@ -40,13 +41,14 @@ public class InternalWikiController {
         return Result.success(articleService.listPublishedArticlesByCategory(categoryId, page, pageSize));
     }
 
-    @ApiOperation("查询已发布文章详情")
+    @ApiOperation(value = "查询已发布文章详情", notes = "**关联字典**：\n- wiki_status：文章状态（返回字段）")
     @GetMapping("/article/{articleId}")
     public Result<Map<String, Object>> getArticle(@PathVariable Long articleId) {
         return Result.success(articleService.getPublishedArticle(articleId));
     }
 
-    @ApiOperation("查询推荐文章列表")
+    @ApiOperation(value = "查询推荐文章列表",
+            notes = "内部服务间调用。返回已发布且标记为推荐的文章列表，用于小程序首页推荐位展示。默认返回5条。")
     @GetMapping("/recommend-articles")
     public Result<List<Map<String, Object>>> listRecommendArticles(
             @RequestParam(defaultValue = "5") Integer limit) {

`hl-insurance-service/src/main/java/com/hulalv/insurance/config/Knife4jConfig.java` (M)

diff --git a/hl-insurance-service/src/main/java/com/hulalv/insurance/config/Knife4jConfig.java b/hl-insurance-service/src/main/java/com/hulalv/insurance/config/Knife4jConfig.java
index 3528af0..9b09f25 100644
--- a/hl-insurance-service/src/main/java/com/hulalv/insurance/config/Knife4jConfig.java
+++ b/hl-insurance-service/src/main/java/com/hulalv/insurance/config/Knife4jConfig.java
@@ -1,9 +1,9 @@
 package com.hulalv.insurance.config;
 
+import com.google.common.base.Predicate;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
-import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
@@ -11,6 +11,11 @@ import springfox.documentation.spring.web.plugins.Docket;
 @Configuration
 public class Knife4jConfig {
 
+    /** 排除内部接口和回调接口路径 */
+    private Predicate<String> adminPaths() {
+        return input -> input != null && !input.contains("/internal/") && !input.contains("/callback/");
+    }
+
     @Bean
     public Docket insuranceApi() {
         return new Docket(DocumentationType.SWAGGER_2)
@@ -22,7 +27,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.insurance.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 }

`hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java` (M)

diff --git a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java
index 852da1c..1505c2c 100644
--- a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java
+++ b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java
@@ -48,7 +48,8 @@ public class AdminInsuranceController {
     private final InsuranceEntityProperties entityProperties;
     private final PolicyShareService policyShareService;
 
-    @ApiOperation("保险产品列表")
+    @ApiOperation(value = "保险产品列表",
+            notes = "分页查询已同步的保险产品，支持按是否境外筛选。产品数据来源于保游网同步。\n\n**权限**：需管理员登录。")
     @GetMapping("/products")
     public Result<PageResult<InsuranceProductVO>> listProducts(
             @ApiParam("页码") @RequestParam(defaultValue = "1") Integer page,
@@ -57,26 +58,30 @@ public class AdminInsuranceController {
         return Result.success(orderService.listProducts(page, pageSize, isOverseas));
     }
 
-    @ApiOperation("保险产品详情")
+    @ApiOperation(value = "保险产品详情",
+            notes = "返回保险产品完整信息，包含产品名称、保险公司、保障范围、适用地区等。\n\n**权限**：需管理员登录。")
     @GetMapping("/products/{id}")
     public Result<InsuranceProductVO> getProduct(@ApiParam("保险产品ID") @PathVariable("id") Long productId) {
         return Result.success(orderService.getProductDetail(productId));
     }
 
-    @ApiOperation("保险产品计划及费率")
+    @ApiOperation(value = "保险产品计划及费率",
+            notes = "返回指定保险产品的所有投保计划及对应费率表，包含不同天数区间的保费价格。投保下单前需选择具体计划。\n\n**权限**：需管理员登录。")
     @GetMapping("/products/{id}/plans")
     public Result<List<InsurancePlanVO>> getProductPlans(@ApiParam("保险产品ID") @PathVariable("id") Long productId) {
         return Result.success(orderService.getProductPlans(productId));
     }
 
-    @ApiOperation("从保游网同步产品数据")
+    @ApiOperation(value = "从保游网同步产品数据",
+            notes = "手动触发从保游网API拉取最新保险产品数据（含计划和费率），同步到本地数据库。返回同步的产品数量。\n\n**权限**：需管理员登录。")
     @PostMapping("/sync-products")
     public Result<Integer> syncProducts() {
         int count = syncService.syncAll();
         return Result.success(count);
     }
 
-    @ApiOperation("投保公司主体列表")
+    @ApiOperation(value = "投保公司主体列表",
+            notes = "返回系统配置的投保公司主体列表（来自Nacos配置），投保下单时选择以哪个公司主体投保。每个主体包含编码、公司名称和商户ID。\n\n**权限**：需管理员登录。")
     @GetMapping("/entities")
     public Result<List<Map<String, String>>> listEntities() {
         List<Map<String, String>> list = entityProperties.getList().stream().map(e -> {
@@ -91,7 +96,7 @@ public class AdminInsuranceController {
         return Result.success(list);
     }
 
-    @ApiOperation("投保下单(每人独立保单)")
+    @ApiOperation(value = "投保下单(每人独立保单)", notes = "**关联字典**：\n- gender：性别（被保人信息）\n- id_card_type：证件类型（被保人信息）")
     @PostMapping("/purchase")
     public Result<List<InsuranceOrderDetailVO>> purchase(
             @ApiParam("投保请求") @Valid @RequestBody PurchaseInsuranceRequest request,
@@ -100,43 +105,48 @@ public class AdminInsuranceController {
         return Result.success(orderService.purchase(request, adminId));
     }
 
-    @ApiOperation("退保")
+    @ApiOperation(value = "退保",
+            notes = "对单个保险订单发起退保，调用保游网退保API。退保成功后保险状态变为CANCELLED。\n\n**权限**：需管理员登录。\n**注意**：已生效的保单退保可能产生手续费。\n\n**关联字典**：\n- insurance_status：保险状态（状态流转）")
     @PostMapping("/cancel/{id}")
     public Result<InsuranceOrderVO> cancel(@ApiParam("保险订单ID") @PathVariable("id") Long insuranceOrderId) {
         return Result.success(orderService.cancel(insuranceOrderId));
     }
 
-    @ApiOperation("保险订单列表")
+    @ApiOperation(value = "保险订单列表", notes = "**关联字典**：\n- insurance_status：保险状态（列表筛选+显示）")
     @GetMapping("/orders")
     public Result<PageResult<InsuranceOrderVO>> listOrders(@ApiParam("查询条件") InsuranceQueryRequest request) {
         return Result.success(orderService.listOrders(request));
     }
 
-    @ApiOperation("保险订单详情(含被保人)")
+    @ApiOperation(value = "保险订单详情(含被保人)", notes = "**关联字典**：\n- insurance_status：保险状态（显示）\n- gender：性别（被保人信息显示）\n- id_card_type：证件类型（被保人信息显示）")
     @GetMapping("/orders/{id}")
     public Result<InsuranceOrderDetailVO> getOrderDetail(@ApiParam("保险订单ID") @PathVariable("id") Long insuranceOrderId) {
         return Result.success(orderService.getOrderDetail(insuranceOrderId));
     }
 
-    @ApiOperation("按旅行订单查询保险单")
+    @ApiOperation(value = "按旅行订单查询保险单",
+            notes = "根据旅行订单ID查询关联的所有保险订单列表。在订单详情页展示保险购买情况。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- insurance_status：保险状态（列表显示）")
     @GetMapping("/orders/by-order/{orderId}")
     public Result<List<InsuranceOrderVO>> getByOrder(@ApiParam("旅行订单ID") @PathVariable Long orderId) {
         return Result.success(orderService.getByOrderId(orderId));
     }
 
-    @ApiOperation("查询订单保险保障(含被保人详情)")
+    @ApiOperation(value = "查询订单保险保障(含被保人详情)",
+            notes = "返回订单维度的保险保障汇总信息，包含覆盖人数、保障期间、每位被保人的保单明细。用于订单详情页的保险保障展示。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- insurance_status：保险状态（显示）\n- gender：性别（被保人信息显示）\n- id_card_type：证件类型（被保人信息显示）")
     @GetMapping("/coverage/{orderId}")
     public Result<InsuranceCoverageVO> getCoverage(@ApiParam("旅行订单ID") @PathVariable Long orderId) {
         return Result.success(orderService.getCoverageByOrderId(orderId));
     }
 
-    @ApiOperation("保费试算(本地费率)")
+    @ApiOperation(value = "保费试算(本地费率)",
+            notes = "根据保险计划、投保天数和人数，使用本地同步的费率表试算保费。不调用保游网API，用于投保前的费用预估。\n\n**权限**：需管理员登录。")
     @PostMapping("/trial-price")
     public Result<Map<String, Object>> trialPrice(@ApiParam("试算请求") @Valid @RequestBody TrialPriceRequest request) {
         return Result.success(orderService.trialPrice(request));
     }
 
-    @ApiOperation("查询保游网账户余额")
+    @ApiOperation(value = "查询保游网账户余额",
+            notes = "查询保游网平台的账户余额，用于管理端展示当前可用投保额度。查询失败时返回null（非关键信息，不影响业务）。\n\n**权限**：需管理员登录。")
     @GetMapping("/balance")
     public Result<JsonNode> getBalance() {
         try {
@@ -152,13 +162,15 @@ public class AdminInsuranceController {
         return Result.success(null);
     }
 
-    @ApiOperation("下载保单PDF(Base64)")
+    @ApiOperation(value = "下载保单PDF(Base64)",
+            notes = "从保游网下载指定保险订单的电子保单PDF，以Base64编码返回。前端可解码后展示或提供下载。\n\n**权限**：需管理员登录。")
     @GetMapping("/policy/{id}/download")
     public Result<String> downloadPolicy(@ApiParam("保险订单ID") @PathVariable("id") Long insuranceOrderId) {
         return Result.success(orderService.downloadPolicy(insuranceOrderId));
     }
 
-    @ApiOperation("获取保游网充值链接(旧接口,保留兼容)")
+    @ApiOperation(value = "获取保游网充值链接(旧接口,保留兼容)",
+            notes = "返回保游网平台的充值页面URL。此为旧版接口，保留用于向后兼容，推荐使用在线充值接口。\n\n**权限**：需管理员登录。")
     @GetMapping("/recharge-url")
     public Result<String> getRechargeUrl() {
         String url = baoyouProperties.getRechargeUrl();
@@ -168,13 +180,15 @@ public class AdminInsuranceController {
         return Result.success(url);
     }
 
-    @ApiOperation("在线充值(调用保游网支付API)")
+    @ApiOperation(value = "在线充值(调用保游网支付API)",
+            notes = "调用保游网在线充值API，生成充值支付链接。支持选择支付方式（支付宝/微信），充值完成后账户余额自动更新。\n\n**权限**：需管理员登录。")
     @PostMapping("/recharge")
     public Result<Map<String, Object>> recharge(@ApiParam("充值请求") @Valid @RequestBody RechargeRequest request) {
         return Result.success(orderService.recharge(request.getMoney(), request.getPayType(), request.getBackUrl()));
     }
 
-    @ApiOperation("分享保单(合并某出行人所有有效保单PDF,上传OSS返回链接)")
+    @ApiOperation(value = "分享保单(合并某出行人所有有效保单PDF,上传OSS返回链接)",
+            notes = "合并指定出行人的所有有效保单PDF为一个文件，上传至OSS后返回公开访问链接。用于管理端分享保单给出行人。\n\n**权限**：需管理员登录。")
     @PostMapping("/share-policy")
     public Result<PolicyShareVO> sharePolicy(
             @ApiParam("分享保单请求") @Valid @RequestBody SharePolicyRequest request) {

`hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java` (M)

diff --git a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java
index 9497720..04db6d6 100644
--- a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java
+++ b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java
@@ -24,26 +24,30 @@ public class AdminInsuranceSchemeController {
 
     private final InsuranceSchemeService schemeService;
 
-    @ApiOperation("活跃方案列表(下拉选择用)")
+    @ApiOperation(value = "活跃方案列表(下拉选择用)",
+            notes = "返回所有状态为启用的保险方案模板，用于投保下单时的方案下拉选择。\n\n**权限**：需管理员登录。")
     @GetMapping("/list")
     public Result<List<InsuranceSchemeVO>> listActiveSchemes() {
         return Result.success(schemeService.listActiveSchemes());
     }
 
-    @ApiOperation("全部方案列表(管理用)")
+    @ApiOperation(value = "全部方案列表(管理用)",
+            notes = "返回所有保险方案模板（含启用和停用），用于方案管理页面展示和编辑。\n\n**权限**：需管理员登录。")
     @GetMapping("/list-all")
     public Result<List<InsuranceSchemeVO>> listAllSchemes() {
         return Result.success(schemeService.listAllSchemes());
     }
 
-    @ApiOperation("方案详情")
+    @ApiOperation(value = "方案详情",
+            notes = "返回单个保险方案模板的完整信息，包含方案名称、保险产品关联、天数规则、费率配置等。\n\n**权限**：需管理员登录。")
     @GetMapping("/{id}")
     public Result<InsuranceSchemeVO> getSchemeDetail(
             @ApiParam("方案ID") @PathVariable("id") Long schemeId) {
         return Result.success(schemeService.getSchemeDetail(schemeId));
     }
 
-    @ApiOperation("创建方案")
+    @ApiOperation(value = "创建方案",
+            notes = "创建保险方案模板，配置关联保险产品、投保天数规则和费率。创建后默认启用。\n\n**权限**：需管理员登录。")
     @PostMapping
     public Result<InsuranceSchemeVO> createScheme(
             @ApiParam("方案请求") @Valid @RequestBody InsuranceSchemeRequest request,
@@ -52,7 +56,8 @@ public class AdminInsuranceSchemeController {
         return Result.success(schemeService.createScheme(request, adminId));
     }
 
-    @ApiOperation("更新方案")
+    @ApiOperation(value = "更新方案",
+            notes = "更新保险方案模板的配置信息，包括方案名称、关联产品、天数规则、费率等。\n\n**权限**：需管理员登录。")
     @PutMapping("/{id}")
     public Result<InsuranceSchemeVO> updateScheme(
             @ApiParam("方案ID") @PathVariable("id") Long schemeId,
@@ -62,14 +67,16 @@ public class AdminInsuranceSchemeController {
         return Result.success(schemeService.updateScheme(schemeId, request, adminId));
     }
 
-    @ApiOperation("切换方案状态(启用/停用)")
+    @ApiOperation(value = "切换方案状态(启用/停用)",
+            notes = "切换保险方案模板的启用/停用状态。停用后不会出现在投保下单的方案选择列表中。\n\n**权限**：需管理员登录。\n\n**关联字典**：\n- common_status：通用状态（ACTIVE=启用/INACTIVE=停用）")
     @PutMapping("/{id}/toggle-status")
     public Result<InsuranceSchemeVO> toggleStatus(
             @ApiParam("方案ID") @PathVariable("id") Long schemeId) {
         return Result.success(schemeService.toggleStatus(schemeId));
     }
 
-    @ApiOperation("删除方案(软删除)")
+    @ApiOperation(value = "删除方案(软删除)",
+            notes = "软删除保险方案模板。已使用该方案创建的保险订单不受影响。\n\n**权限**：需管理员登录。")
     @DeleteMapping("/{id}")
     public Result<Void> deleteScheme(
             @ApiParam("方案ID") @PathVariable("id") Long schemeId) {
@@ -77,7 +84,8 @@ public class AdminInsuranceSchemeController {
         return Result.success(null);
     }
 
-    @ApiOperation("预览应用方案(解析日期+估算保费)")
+    @ApiOperation(value = "预览应用方案(解析日期+估算保费)",
+            notes = "根据方案模板和行程日期预览投保效果：解析实际投保起止日期、计算每人保费和总保费。用于投保前确认费用。\n\n**权限**：需管理员登录。")
     @PostMapping("/preview-apply")
     public Result<ApplySchemePreviewVO> previewApply(
             @ApiParam("预览请求") @Valid @RequestBody ApplySchemeRequest request) {

`hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java` (M)

diff --git a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java
index 828cc04..d77d99e 100644
--- a/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java
+++ b/hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java
@@ -16,7 +16,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "【内部接口】保险（Feign调用）")
+@Api(tags = "【内部接口】保险（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/insurance")
 @RequiredArgsConstructor
@@ -26,19 +26,22 @@ public class InternalInsuranceController {
     private final InsuranceProductSyncService syncService;
     private final PolicyShareService policyShareService;
 
-    @ApiOperation("按旅行订单查询保险单(内部调用)")
+    @ApiOperation(value = "按旅行订单查询保险单(内部调用)",
+            notes = "内部服务间调用。根据旅行订单ID查询关联的所有保险订单，返回保险状态、保费、保障期间等信息。\n\n**关联字典**：\n- insurance_status：保险状态（返回字段）")
     @GetMapping("/by-order/{orderId}")
     public Result<List<InsuranceOrderVO>> getByOrder(@ApiParam("旅行订单ID") @PathVariable Long orderId) {
         return Result.success(orderService.getByOrderId(orderId));
     }
 
-    @ApiOperation("按订单批量查询保险单(内部调用)")
+    @ApiOperation(value = "按订单批量查询保险单(内部调用)",
+            notes = "内部服务间调用。批量查询多个旅行订单的保险订单，返回Map结构（key=订单ID，value=保险单列表），用于订单列表页展示保险状态。")
     @PostMapping("/by-orders")
     public Result<Map<Long, List<InsuranceOrderVO>>> getByOrders(@RequestBody List<Long> orderIds) {
         return Result.success(orderService.getByOrderIds(orderIds));
     }
 
-    @ApiOperation("检查保险是否全覆盖(内部调用)")
+    @ApiOperation(value = "检查保险是否全覆盖(内部调用)",
+            notes = "内部服务间调用。根据出行人数和行程天数计算所需的人日数，与已投保的有效保单覆盖人日数对比，判断保险是否已全覆盖。")
     @GetMapping("/coverage-complete/{orderId}")
     public Result<Boolean> isCoverageComplete(
             @ApiParam("旅行订单ID") @PathVariable Long orderId,
@@ -57,7 +60,8 @@ public class InternalInsuranceController {
         return Result.success(coveredPersonDays >= requiredPersonDays);
     }
 
-    @ApiOperation("按订单批量退保(级联失效调用)")
+    @ApiOperation(value = "按订单批量退保(级联失效调用)",
+            notes = "内部服务间调用。旅行订单取消或退款时级联调用，将该订单下所有有效保险单批量退保（调用保游网退保API），记录退保原因。")
     @PostMapping("/invalidate/{orderId}")
     public Result<Void> invalidateInsurance(
             @ApiParam("旅行订单ID") @PathVariable Long orderId,
@@ -66,19 +70,22 @@ public class InternalInsuranceController {
         return Result.success(null);
     }
 
-    @ApiOperation("分享保单PDF(内部调用,返回base64)")
+    @ApiOperation(value = "分享保单PDF(内部调用,返回base64)",
+            notes = "内部服务间调用。合并指定出行人的所有有效保单PDF为一个文件，上传至OSS后返回下载链接和Base64内容，用于小程序端分享保单。")
     @PostMapping("/share-policy")
     public Result<PolicyShareVO> sharePolicy(@RequestBody SharePolicyRequest request) {
         return Result.success(policyShareService.sharePolicy(request));
     }
 
-    @ApiOperation("按订单获取所有保单PDF(内部调用,合并所有出行人)")
+    @ApiOperation(value = "按订单获取所有保单PDF(内部调用,合并所有出行人)",
+            notes = "内部服务间调用。将指定订单下所有出行人的有效保单PDF合并为一个文件，上传至OSS后返回下载链接，用于订单维度的保单查看。")
     @GetMapping("/share-policy-by-order/{orderId}")
     public Result<PolicyShareVO> sharePolicyByOrder(@PathVariable Long orderId) {
         return Result.success(policyShareService.sharePolicyByOrder(orderId));
     }
 
-    @ApiOperation("触发保险产品同步(内部调用/定时任务)")
+    @ApiOperation(value = "触发保险产品同步(内部调用/定时任务)",
+            notes = "内部服务间调用。从保游网API拉取最新保险产品数据（含计划和费率），同步到本地数据库。返回同步的产品数量。")
     @PostMapping("/sync-products")
     public Result<Integer> syncProducts() {
         int count = syncService.syncAll();

`hl-material-service/src/main/java/com/hulalv/material/config/Knife4jConfig.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/config/Knife4jConfig.java b/hl-material-service/src/main/java/com/hulalv/material/config/Knife4jConfig.java
index 93e40f0..c55eaa0 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/config/Knife4jConfig.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/config/Knife4jConfig.java
@@ -1,9 +1,9 @@
 package com.hulalv.material.config;
 
+import com.google.common.base.Predicate;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
-import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
@@ -11,6 +11,11 @@ import springfox.documentation.spring.web.plugins.Docket;
 @Configuration
 public class Knife4jConfig {
 
+    /** 排除内部接口和回调接口路径 */
+    private Predicate<String> adminPaths() {
+        return input -> input != null && !input.contains("/internal/") && !input.contains("/callback/");
+    }
+
     @Bean
     public Docket materialApi() {
         return new Docket(DocumentationType.SWAGGER_2)
@@ -22,7 +27,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.material.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 }

`hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java b/hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java
index 08122a4..686a577 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java
@@ -22,7 +22,7 @@ import java.util.List;
  * Internal endpoints for Feign calls from other services (scenic, hotel, etc.).
  * Not exposed through gateway.
  */
-@Api(tags = "素材内部接口（Feign调用）")
+@Api(tags = "素材内部接口（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/material")
 @RequiredArgsConstructor
@@ -31,7 +31,7 @@ public class InternalMaterialController {
     private final MaterialRefService refService;
     private final MaterialService materialService;
 
-    @ApiOperation("绑定引用")
+    @ApiOperation(value = "绑定引用", notes = "将素材与业务实体建立引用关系（如景区ID+封面图），记录引用类型（COVER/GALLERY/DETAIL等）")
     @PostMapping("/ref/bind")
     public Result<Void> bindRef(
             @Valid @RequestBody RefBindRequest request,
@@ -40,7 +40,7 @@ public class InternalMaterialController {
         return Result.success();
     }
 
-    @ApiOperation("批量绑定引用")
+    @ApiOperation(value = "批量绑定引用", notes = "批量建立素材与业务实体的引用关系，常用于保存包含多张图片的业务数据")
     @PostMapping("/ref/batch-bind")
     public Result<Void> batchBindRefs(
             @Valid @RequestBody RefBatchBindRequest request,
@@ -49,7 +49,7 @@ public class InternalMaterialController {
         return Result.success();
     }
 
-    @ApiOperation("解绑引用")
+    @ApiOperation(value = "解绑引用", notes = "删除单个素材与业务实体的引用关系")
     @DeleteMapping("/ref/unbind")
     public Result<Void> unbindRef(@Valid @RequestBody RefUnbindRequest request) {
         refService.unbindRef(request.getMaterialId(), request.getBizType(),
@@ -57,14 +57,15 @@ public class InternalMaterialController {
         return Result.success();
     }
 
-    @ApiOperation("批量解绑引用")
+    @ApiOperation(value = "批量解绑引用", notes = "批量删除素材引用关系，常用于业务实体更新时先清除旧引用再绑定新引用")
     @DeleteMapping("/ref/batch-unbind")
     public Result<Void> batchUnbindRefs(@Valid @RequestBody RefBatchUnbindRequest request) {
         refService.batchUnbindRefs(request.getRefs());
         return Result.success();
     }
 
-    @ApiOperation("批量查询素材信息")
+    @ApiOperation(value = "批量查询素材信息",
+            notes = "内部服务间调用。根据素材ID列表批量查询素材信息，用于其他服务获取素材详情（如产品、景区等关联的素材数据）。")
     @PostMapping("/by-ids")
     public Result<List<MaterialVO>> getMaterialsByIds(@Valid @RequestBody BatchMaterialIdsRequest request) {
         return Result.success(materialService.getMaterialsByIds(request.getMaterialIds()));

`hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java
index 03566eb..77fa5a6 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java
@@ -23,7 +23,7 @@ public class MaterialCategoryPermissionController {
 
     private final MaterialCategoryPermissionService permissionService;
 
-    @ApiOperation("获取角色的分类权限")
+    @ApiOperation(value = "获取角色的分类权限", notes = "仅超级管理员可操作。返回指定角色可访问的素材分类编码列表")
     @GetMapping("/{roleCode}")
     public Result<List<String>> getPermissions(
             @ApiParam("角色编码") @PathVariable String roleCode,
@@ -32,7 +32,7 @@ public class MaterialCategoryPermissionController {
         return Result.success(permissionService.getPermissionsByRoleCode(roleCode));
     }
 
-    @ApiOperation("更新角色的分类权限")
+    @ApiOperation(value = "更新角色的分类权限", notes = "仅超级管理员可操作。全量替换指定角色的素材分类访问权限，传入允许访问的分类编码列表")
     @PutMapping("/{roleCode}")
     public Result<Void> updatePermissions(
             @ApiParam("角色编码") @PathVariable String roleCode,

`hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java
index 0fa7c7e..d79def9 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java
@@ -47,7 +47,7 @@ public class MaterialController {
 
     // ==================== Upload ====================
 
-    @ApiOperation("获取上传凭证")
+    @ApiOperation(value = "获取上传凭证", notes = "上传素材第一步：获取OSS预签名URL和凭证。前端使用凭证直传OSS后调用确认上传。支持基于角色的分类权限校验")
     @PostMapping("/upload/token")
     public Result<MaterialUploadTokenVO> requestUploadToken(
             @ApiParam("上传凭证请求") @Valid @RequestBody MaterialUploadTokenRequest request,
@@ -57,7 +57,7 @@ public class MaterialController {
         return Result.success(materialService.requestUploadToken(request, adminId, role));
     }
 
-    @ApiOperation("确认上传完成")
+    @ApiOperation(value = "确认上传完成", notes = "上传素材第二步：前端直传OSS完成后调用此接口创建素材记录，支持MD5去重\n\n**关联字典**：\n- material_tag：素材标签（上传时可选标签）")
     @PostMapping("/upload/confirm")
     public Result<MaterialVO> confirmUpload(
             @ApiParam("确认上传请求") @Valid @RequestBody MaterialUploadConfirmRequest request,
@@ -66,7 +66,7 @@ public class MaterialController {
         return Result.success(materialService.confirmUpload(request, adminId));
     }
 
-    @ApiOperation("文件夹上传初始化（创建分类+批量获取凭证）")
+    @ApiOperation(value = "文件夹上传初始化（创建分类+批量获取凭证）", notes = "支持整个文件夹上传：自动根据文件夹名创建子分类，为每个文件批量获取上传凭证，前端逐一上传后批量确认")
     @PostMapping("/upload/folder")
     public Result<FolderUploadInitVO> folderUploadInit(
             @ApiParam("文件夹上传初始化请求") @Valid @RequestBody FolderUploadInitRequest request,
@@ -79,7 +79,8 @@ public class MaterialController {
 
     // ==================== Chunk Upload (分片上传) ====================
 
-    @ApiOperation("分片上传-初始化")
+    @ApiOperation(value = "分片上传-初始化",
+            notes = "大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用完成合并接口。\n\n**权限**：需管理员登录，受角色分类权限限制。")
     @PostMapping("/upload/chunk/init")
     public Result<ChunkUploadInitVO> chunkUploadInit(
             @ApiParam("分片上传初始化请求") @Valid @RequestBody ChunkUploadInitRequest request,
@@ -89,7 +90,8 @@ public class MaterialController {
         return Result.success(chunkUploadService.initChunkUpload(request, adminId, role));
     }
 
-    @ApiOperation("分片上传-上传分片")
+    @ApiOperation(value = "分片上传-上传分片",
+            notes = "大文件上传第二步：逐个上传分片数据，分片索引从0开始。支持断点续传，已上传的分片无需重传。")
     @PostMapping("/upload/chunk")
     public Result<ChunkUploadPartVO> chunkUploadPart(
             @ApiParam("上传ID") @RequestParam("uploadId") String uploadId,
@@ -99,7 +101,8 @@ public class MaterialController {
         return Result.success(chunkUploadService.uploadChunk(uploadId, chunkIndex, chunk));
     }
 
-    @ApiOperation("分片上传-完成合并")
+    @ApiOperation(value = "分片上传-完成合并",
+            notes = "大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建素材记录。")
     @PostMapping("/upload/chunk/complete")
     public Result<MaterialVO> chunkUploadComplete(
             @ApiParam("分片上传完成请求") @Valid @RequestBody ChunkUploadCompleteRequest request,
@@ -108,7 +111,8 @@ public class MaterialController {
         return Result.success(chunkUploadService.completeChunkUpload(request.getUploadId(), adminId));
     }
 
-    @ApiOperation("分片上传-取消")
+    @ApiOperation(value = "分片上传-取消",
+            notes = "取消分片上传任务，清理已上传的分片数据和OSS临时文件。仅上传发起者可取消。")
     @PostMapping("/upload/chunk/cancel")
     public Result<Void> chunkUploadCancel(
             @ApiParam("分片上传取消请求") @Valid @RequestBody ChunkUploadCancelRequest request,
@@ -120,7 +124,7 @@ public class MaterialController {
 
     // ==================== CRUD ====================
 
-    @ApiOperation("素材列表")
+    @ApiOperation(value = "素材列表", notes = "分页查询素材，支持按分类、标签、文件类型、关键词筛选。返回结果受角色分类权限限制\n\n**关联字典**：\n- file_type：文件类型（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<MaterialVO>> listMaterials(
             @ApiParam("素材查询条件") @Valid MaterialQueryRequest query,
@@ -131,7 +135,8 @@ public class MaterialController {
         return Result.success(materialService.listMaterials(query, adminId, role, categoryMap));
     }
 
-    @ApiOperation("素材详情")
+    @ApiOperation(value = "素材详情",
+            notes = "返回素材完整信息，包含文件名、URL、分类、标签、文件大小、上传者等。受角色分类权限限制。\n\n**关联字典**：\n- file_type：文件类型（显示）")
     @GetMapping("/{materialId}")
     public Result<MaterialVO> getMaterial(
             @ApiParam("素材ID") @PathVariable Long materialId,
@@ -141,7 +146,7 @@ public class MaterialController {
         return Result.success(materialService.getMaterial(materialId, role, categoryMap));
     }
 
-    @ApiOperation("更新素材信息")
+    @ApiOperation(value = "更新素材信息", notes = "**关联字典**：\n- material_tag：素材标签（编辑时选择标签）")
     @PutMapping("/{materialId}")
     public Result<MaterialVO> updateMaterial(
             @ApiParam("素材ID") @PathVariable Long materialId,
@@ -153,7 +158,7 @@ public class MaterialController {
         return Result.success(materialService.updateMaterial(materialId, request, adminId, role, categoryMap));
     }
 
-    @ApiOperation("删除素材")
+    @ApiOperation(value = "删除素材", notes = "删除素材记录。如果素材存在引用关系（被景区、酒店等使用），则不允许删除")
     @DeleteMapping("/{materialId}")
     public Result<Void> deleteMaterial(
             @ApiParam("素材ID") @PathVariable Long materialId,
@@ -164,7 +169,7 @@ public class MaterialController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除素材")
+    @ApiOperation(value = "批量删除素材", notes = "批量删除素材，返回删除结果（成功数/失败数/失败原因）。有引用关系的素材会跳过并记录失败原因")
     @DeleteMapping("/batch")
     public Result<BatchDeleteResultVO> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,
@@ -179,7 +184,7 @@ public class MaterialController {
 
     // ==================== Tags on Materials ====================
 
-    @ApiOperation("更新素材标签")
+    @ApiOperation(value = "更新素材标签", notes = "全量替换单个素材的标签，传入新的标签ID列表")
     @PutMapping("/{materialId}/tags")
     public Result<Void> updateMaterialTags(
             @ApiParam("素材ID") @PathVariable Long materialId,
@@ -192,7 +197,7 @@ public class MaterialController {
         return Result.success();
     }
 
-    @ApiOperation("批量更新标签")
+    @ApiOperation(value = "批量更新标签", notes = "对多个素材同时添加和/或移除标签，支持增量操作（addTagIds新增，removeTagIds移除）")
     @PutMapping("/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签更新请求") @Valid @RequestBody BatchTagRequest request,
@@ -212,7 +217,7 @@ public class MaterialController {
 
     // ==================== References ====================
 
-    @ApiOperation("查看素材引用记录")
+    @ApiOperation(value = "查看素材引用记录", notes = "查看素材被哪些业务实体引用（如景区封面、酒店轮播图等），用于判断素材是否可安全删除")
     @GetMapping("/{materialId}/refs")
     public Result<List<MaterialRefVO>> getMaterialRefs(@ApiParam("素材ID") @PathVariable Long materialId) {
         return Result.success(refService.getRefsByMaterialId(materialId));
@@ -220,7 +225,7 @@ public class MaterialController {
 
     // ==================== Categories ====================
 
-    @ApiOperation("获取有权限的分类列表（含素材数量）")
+    @ApiOperation(value = "获取有权限的分类列表（含素材数量）", notes = "返回当前角色有权限查看的素材分类树，每个分类包含素材数量统计。超级管理员可见全部分类")
     @GetMapping("/categories")
     public Result<List<CategoryVO>> getCategories(HttpServletRequest httpRequest) {
         String role = getRole(httpRequest);
@@ -230,7 +235,7 @@ public class MaterialController {
 
     // ==================== Sub-categories ====================
 
-    @ApiOperation("创建子分类")
+    @ApiOperation(value = "创建子分类", notes = "在一级分类下创建子分类，分类编码自动生成。子分类用于更细粒度的素材归档")
     @PostMapping("/category/sub")
     public Result<CategoryVO> createSubCategory(
             @ApiParam("子分类创建请求") @Valid @RequestBody SubCategoryCreateRequest request,
@@ -241,7 +246,8 @@ public class MaterialController {
         return Result.success(categoryService.createSubCategory(request, adminId, role, categoryMap));
     }
 
-    @ApiOperation("更新子分类")
+    @ApiOperation(value = "更新子分类",
+            notes = "更新子分类的名称或排序值。仅有该分类权限的管理员可操作。")
     @PutMapping("/category/sub/{categoryId}")
     public Result<CategoryVO> updateSubCategory(
             @ApiParam("子分类ID") @PathVariable Long categoryId,
@@ -252,7 +258,7 @@ public class MaterialController {
         return Result.success(categoryService.updateSubCategory(categoryId, request, adminId, role));
     }
 
-    @ApiOperation("删除子分类")
+    @ApiOperation(value = "删除子分类", notes = "删除子分类前需确保分类下无素材，否则删除失败")
     @DeleteMapping("/category/sub/{categoryId}")
     public Result<Void> deleteSubCategory(
             @ApiParam("子分类ID") @PathVariable Long categoryId,

`hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java
index a90884f..31d53b5 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java
@@ -23,19 +23,22 @@ public class MaterialTagController {
 
     private final MaterialTagService tagService;
 
-    @ApiOperation("获取管理标签（标签管理用）")
+    @ApiOperation(value = "获取管理标签（标签管理用）",
+            notes = "返回管理员创建的系统标签列表（不含用户自定义标签），用于标签管理页的CRUD操作。")
     @GetMapping("/tags")
     public Result<List<MaterialTagVO>> listManagedTags() {
         return Result.success(tagService.listManagedTags());
     }
 
-    @ApiOperation("获取全部标签（选择器用，含自定义标签）")
+    @ApiOperation(value = "获取全部标签（选择器用，含自定义标签）",
+            notes = "返回所有标签（含系统标签和用户自定义标签），用于素材上传/编辑时的标签选择器。")
     @GetMapping("/tags/all")
     public Result<List<MaterialTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建管理标签")
+    @ApiOperation(value = "创建管理标签",
+            notes = "创建系统级素材标签，标签名称不可重复。创建后可用于素材分类和筛选。\n\n**权限**：需管理员登录。")
     @PostMapping("/tag")
     public Result<MaterialTagVO> createTag(
             @ApiParam("创建标签请求") @Valid @RequestBody TagCreateRequest request,
@@ -44,7 +47,8 @@ public class MaterialTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签（按名称查找或创建）")
+    @ApiOperation(value = "解析自定义标签（按名称查找或创建）",
+            notes = "按标签名称查找已有标签，不存在则自动创建为用户自定义标签。用于素材上传时输入自由标签文本的场景。\n\n**权限**：需管理员登录。")
     @PostMapping("/tag/adhoc")
     public Result<MaterialTagVO> resolveAdHocTag(
             @ApiParam("自定义标签请求") @RequestBody TagCreateRequest request,
@@ -53,7 +57,8 @@ public class MaterialTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("编辑标签")
+    @ApiOperation(value = "编辑标签",
+            notes = "更新标签名称。标签名称不可与其他已有标签重复。\n\n**权限**：需管理员登录。")
     @PutMapping("/tag/{tagId}")
     public Result<MaterialTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -61,7 +66,8 @@ public class MaterialTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签",
+            notes = "删除标签并自动解除与所有素材的关联关系。\n\n**权限**：需管理员登录。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);

`hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java b/hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java
index a595577..17f64ac 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java
@@ -20,7 +20,7 @@ public class MpMaterialController {
 
     private final MaterialService materialService;
 
-    @ApiOperation("获取小程序分类下的全部素材")
+    @ApiOperation(value = "获取小程序分类下的全部素材", notes = "返回miniprogram分类下的所有素材，用于小程序端展示公共素材资源（如引导页图片、默认头像等）")
     @GetMapping("/miniprogram")
     public Result<List<MaterialVO>> listMiniprogramMaterials() {
         return Result.success(materialService.listMaterialsByCategoryCode("miniprogram"));

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java
index 7adbe0a..93a06f8 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java
@@ -1,9 +1,13 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("分片上传取消请求")
 public class ChunkUploadCancelRequest {
 
+    @ApiModelProperty("上传ID")
     private String uploadId;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java
index 712c15c..d876fcc 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java
@@ -1,9 +1,13 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("分片上传完成请求")
 public class ChunkUploadCompleteRequest {
 
+    @ApiModelProperty("上传ID")
     private String uploadId;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java
index 2d94f04..939a630 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java
@@ -1,13 +1,25 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("分片上传初始化请求")
 public class ChunkUploadInitRequest {
 
+    @ApiModelProperty("文件名")
     private String filename;
+
+    @ApiModelProperty("文件大小(字节)")
     private Long fileSize;
+
+    @ApiModelProperty("文件MIME类型")
     private String contentType;
+
+    @ApiModelProperty("分组标识")
     private String groupKey;
+
+    @ApiModelProperty("文件哈希值")
     private String fileHash;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java
index 96c2499..449c3b4 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,7 +11,9 @@ import java.util.List;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("文件批量ID请求")
 public class FileBatchIdsRequest {
 
+    @ApiModelProperty("文件ID列表")
     private List<Long> fileIds;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java
index bb85acc..1b1d316 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java
@@ -1,9 +1,13 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("文件上传确认请求")
 public class FileUploadConfirmRequest {
 
+    @ApiModelProperty("文件ID")
     private String fileId;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java
index 4d7a140..ee7cd4e 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java
@@ -1,13 +1,25 @@
 package com.hulalv.material.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("文件上传令牌请求")
 public class FileUploadTokenRequest {
 
+    @ApiModelProperty("文件名")
     private String fileName;
+
+    @ApiModelProperty("文件大小(字节)")
     private Long fileSize;
+
+    @ApiModelProperty("文件哈希值")
     private String fileHash;
+
+    @ApiModelProperty("分组标识")
     private String groupKey;
+
+    @ApiModelProperty("是否强制使用预签名URL")
     private boolean forcePresigned;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java
index 6cd60b6..9f38bc4 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java
@@ -1,12 +1,22 @@
 package com.hulalv.material.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("分片上传初始化结果")
 public class ChunkUploadInitVO {
 
+    @ApiModelProperty("上传ID")
     private String uploadId;
+
+    @ApiModelProperty("分片大小(字节)")
     private int chunkSize;
+
+    @ApiModelProperty("文件ID")
     private String fileId;
+
+    @ApiModelProperty("OSS对象Key")
     private String ossKey;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java
index 1628687..cc0df47 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java
@@ -1,9 +1,13 @@
 package com.hulalv.material.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("分片上传片段结果")
 public class ChunkUploadPartVO {
 
+    @ApiModelProperty("分片ETag标识")
     private String etag;
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java
index 779f74d..07b2068 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java
@@ -1,28 +1,58 @@
 package com.hulalv.material.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 import java.time.LocalDateTime;
 
 @Data
+@ApiModel("文件上传令牌结果")
 public class FileUploadTokenVO {
 
+    @ApiModelProperty("文件ID")
     private String fileId;
+
+    @ApiModelProperty("文件MIME类型")
     private String contentType;
+
+    @ApiModelProperty("上传模式")
     private String uploadMode;
+
+    @ApiModelProperty("预签名上传URL")
     private String presignedUrl;
+
+    @ApiModelProperty("OSS对象Key")
     private String ossKey;
+
+    @ApiModelProperty("过期时间")
     private LocalDateTime expireAt;
+
+    @ApiModelProperty("STS临时凭证")
     private StsTokenInfo stsToken;
+
+    @ApiModelProperty("OSS存储桶名称")
     private String bucket;
+
+    @ApiModelProperty("OSS区域")
     private String region;
+
+    @ApiModelProperty("文件信息(秒传时返回)")
     private FileVO file;
 
     @Data
+    @ApiModel("STS临时凭证信息")
     public static class StsTokenInfo {
+        @ApiModelProperty("访问密钥ID")
         private String accessKeyId;
+
+        @ApiModelProperty("访问密钥Secret")
         private String accessKeySecret;
+
+        @ApiModelProperty("安全令牌")
         private String securityToken;
+
+        @ApiModelProperty("过期时间")
         private String expiration;
     }
 }

`hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java` (M)

diff --git a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java
index a5e43b9..90612e6 100644
--- a/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java
+++ b/hl-material-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java
@@ -1,23 +1,51 @@
 package com.hulalv.material.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 import java.time.LocalDateTime;
 
 @Data
+@ApiModel("文件信息VO")
 public class FileVO {
 
+    @ApiModelProperty("文件ID")
     private String fileId;
+
+    @ApiModelProperty("文件名")
     private String fileName;
+
+    @ApiModelProperty("文件类型")
     private String fileType;
+
+    @ApiModelProperty("MIME类型")
     private String mimeType;
+
+    @ApiModelProperty("文件大小(字节)")
     private Long fileSize;
+
+    @ApiModelProperty("文件哈希值")
     private String fileHash;
+
+    @ApiModelProperty("OSS访问URL")
     private String ossUrl;
+
+    @ApiModelProperty("缩略图URL")
     private String thumbnailUrl;
+
+    @ApiModelProperty("预览URL")
     private String previewUrl;
+
+    @ApiModelProperty("分组标识")
     private String groupKey;
+
+    @ApiModelProperty("文件状态")
     private String status;
+
+    @ApiModelProperty("引用次数")
     private Integer refCount;
+
+    @ApiModelProperty("创建时间")
     private LocalDateTime createdAt;
 }

`hl-monitor-service/src/main/java/com/hulalv/monitor/config/Knife4jConfig.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/config/Knife4jConfig.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/config/Knife4jConfig.java
index 23786d4..4e0d06b 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/config/Knife4jConfig.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/config/Knife4jConfig.java
@@ -19,7 +19,8 @@ public class Knife4jConfig {
                 .apiInfo(apiInfo())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.monitor.controller"))
-                .paths(PathSelectors.any())
+                .paths(PathSelectors.ant("/internal/**").negate()
+                        .and(PathSelectors.ant("/callback/**").negate()))
                 .build();
     }

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java
index 6c26fc1..04d1ebd 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java
@@ -19,7 +19,7 @@ public class ApprovalLogController {
 
     private final ApprovalLogService approvalLogService;
 
-    @ApiOperation("审批日志分页查询")
+    @ApiOperation(value = "审批日志分页查询", notes = "查询企微OA审批流程记录，支持按审批状态(1-审批中/2-已通过/3-已驳回/4-已撤销)、申请人、模板名称筛选\n\n**关联字典**：\n- approval_sp_status：审批状态（列表筛选+显示）")
     @GetMapping
     public Result<PageResult<ApprovalLog>> list(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -32,7 +32,7 @@ public class ApprovalLogController {
         return Result.success(approvalLogService.queryPage(page, pageSize, spStatus, applyUserName, spName, startTime, endTime));
     }
 
-    @ApiOperation("审批日志详情")
+    @ApiOperation(value = "审批日志详情", notes = "**关联字典**：\n- approval_sp_status：审批状态（显示）")
     @GetMapping("/{id}")
     public Result<ApprovalLog> detail(@ApiParam("日志ID") @PathVariable Long id) {
         ApprovalLog approvalLog = approvalLogService.getById(id);

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java
index 43d56d8..12117da 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java
@@ -19,7 +19,7 @@ public class DataRetentionController {
 
     private final DataRetentionService dataRetentionService;
 
-    @ApiOperation("手动触发数据清理")
+    @ApiOperation(value = "手动触发数据清理", notes = "仅超级管理员可操作。按数据保留策略清理过期日志（操作日志/错误日志/通知日志等），返回各类型清理的记录数")
     @PostMapping("/cleanup")
     public Result<Map<String, Integer>> cleanup(HttpServletRequest request) {
         requireSuperAdmin(request);

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java
index 77046be..06bbdf5 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java
@@ -19,7 +19,7 @@ public class ErrorLogController {
 
     private final ErrorLogService errorLogService;
 
-    @ApiOperation("错误日志分页查询")
+    @ApiOperation(value = "错误日志分页查询", notes = "查询各微服务的异常记录，支持按服务名称、异常类名、时间范围筛选。堆栈信息仅保留com.hulalv包内的调用帧")
     @GetMapping
     public Result<PageResult<ErrorLog>> list(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -31,7 +31,8 @@ public class ErrorLogController {
         return Result.success(errorLogService.queryPage(page, pageSize, serviceName, exceptionClass, startTime, endTime));
     }
 
-    @ApiOperation("错误日志详情")
+    @ApiOperation(value = "错误日志详情",
+            notes = "返回单条错误日志的完整信息，包含异常类名、错误消息、过滤后的堆栈信息（仅com.hulalv包内调用帧）、请求URL、请求参数等。")
     @GetMapping("/{id}")
     public Result<ErrorLog> detail(@ApiParam("日志ID") @PathVariable Long id) {
         ErrorLog errorLog = errorLogService.getById(id);

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java
index 51e3999..44d463e 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java
@@ -18,7 +18,7 @@ import org.springframework.web.bind.annotation.*;
  * Internal endpoints for receiving logs from other services.
  * NOT exposed via gateway.
  */
-@Api(tags = "【内部接口】日志接收（Feign调用）")
+@Api(tags = "【内部接口】日志接收（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/monitor")
 @RequiredArgsConstructor
@@ -29,35 +29,35 @@ public class InternalLogController {
     private final NotificationLogService notificationLogService;
     private final ApprovalLogService approvalLogService;
 
-    @ApiOperation("Receive operation log")
+    @ApiOperation(value = "接收操作日志", notes = "各微服务通过AOP拦截@OperationLog注解的方法，异步发送操作日志到此接口存储")
     @PostMapping("/operation-log")
-    public Result<?> receiveOperationLog(@RequestBody OperationLogDTO dto) {
+    public Result<Void> receiveOperationLog(@RequestBody OperationLogDTO dto) {
         operationLogService.saveFromDTO(dto);
         return Result.success();
     }
 
-    @ApiOperation("Receive error log")
+    @ApiOperation(value = "接收错误日志", notes = "各微服务的GlobalExceptionHandler捕获异常后，异步发送错误日志到此接口存储")
     @PostMapping("/error-log")
-    public Result<?> receiveErrorLog(@RequestBody ErrorLogDTO dto) {
+    public Result<Void> receiveErrorLog(@RequestBody ErrorLogDTO dto) {
         errorLogService.saveFromDTO(dto);
         return Result.success();
     }
 
-    @ApiOperation("Receive notification log")
+    @ApiOperation(value = "接收通知日志", notes = "通知服务发送消息（短信/站内信/企微等）后，记录发送结果到此接口")
     @PostMapping("/notification-log")
-    public Result<?> receiveNotificationLog(@RequestBody NotificationLogDTO dto) {
+    public Result<Void> receiveNotificationLog(@RequestBody NotificationLogDTO dto) {
         notificationLogService.saveFromDTO(dto);
         return Result.success();
     }
 
-    @ApiOperation("Receive approval log")
+    @ApiOperation(value = "接收审批日志", notes = "企微回调服务接收审批事件后，发送审批日志到此接口。同一审批单号会更新已有记录（按thirdNo去重）")
     @PostMapping("/approval-log")
-    public Result<?> receiveApprovalLog(@RequestBody ApprovalLogDTO dto) {
+    public Result<Void> receiveApprovalLog(@RequestBody ApprovalLogDTO dto) {
         approvalLogService.saveOrUpdateByThirdNo(dto);
         return Result.success();
     }
 
-    @ApiOperation("Get customer stats for a user (add/loss counts)")
+    @ApiOperation(value = "获取用户客户统计", notes = "统计指定用户的客户增减数据（新增客户数/流失客户数），用于客户管理看板")
     @GetMapping("/notification-log/customer-stats")
     public Result<java.util.Map<String, Object>> getCustomerStats(
             @RequestParam("userId") String userId) {

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java
index 52c9e86..bc58580 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java
@@ -19,7 +19,7 @@ public class LoginLogController {
 
     private final UserServiceClient userServiceClient;
 
-    @ApiOperation("登录日志分页查询")
+    @ApiOperation(value = "登录日志分页查询", notes = "查询管理员登录记录（代理到user-service），包含登录IP、设备信息、登录方式和登录结果\n\n**关联字典**：\n- login_status：登录状态（列表筛选+显示）")
     @GetMapping
     public Result<?> list(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java
index 029e317..0d29b88 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java
@@ -21,20 +21,20 @@ public class MysqlMonitorController {
 
     private final MysqlMonitorService mysqlMonitorService;
 
-    @ApiOperation("MySQL实时监控数据")
+    @ApiOperation(value = "MySQL实时监控数据", notes = "返回MySQL实时状态：连接数、QPS、缓冲池命中率、线程状态、慢查询计数等核心指标")
     @GetMapping
     public Result<Map<String, Object>> overview() {
         return Result.success(mysqlMonitorService.getOverview());
     }
 
-    @ApiOperation("表空间列表")
+    @ApiOperation(value = "表空间列表", notes = "查询各数据库表的空间占用情况，包含数据大小、索引大小、行数等信息。可指定schema筛选，仅允许查询hl_前缀的数据库")
     @GetMapping("/tables")
     public Result<List<Map<String, Object>>> tables(
             @ApiParam("数据库名") @RequestParam(required = false) String schema) {
         return Result.success(mysqlMonitorService.getTableSpaces(schema));
     }
 
-    @ApiOperation("慢SQL查询统计")
+    @ApiOperation(value = "慢SQL查询统计", notes = "仅超级管理员可操作。查询慢SQL统计信息，返回执行时间最长的SQL语句及其执行次数、平均耗时等")
     @GetMapping("/slow-queries")
     public Result<List<Map<String, Object>>> slowQueries(
             HttpServletRequest request,

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java
index 7e55cae..46d7b72 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java
@@ -19,7 +19,7 @@ public class NotificationLogController {
 
     private final NotificationLogService notificationLogService;
 
-    @ApiOperation("消息通知日志分页查询")
+    @ApiOperation(value = "消息通知日志分页查询", notes = "查询各渠道（短信/站内信/企微/公众号）的通知发送记录，支持按通知类型、用户、发送状态筛选\n\n**关联字典**：\n- notification_send_status：发送状态（列表筛选+显示，0=待发送/1=成功/2=失败）")
     @GetMapping
     public Result<PageResult<NotificationLog>> list(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -32,7 +32,8 @@ public class NotificationLogController {
         return Result.success(notificationLogService.queryPage(page, pageSize, notificationType, userName, sendStatus, startTime, endTime));
     }
 
-    @ApiOperation("消息通知日志详情")
+    @ApiOperation(value = "消息通知日志详情",
+            notes = "返回单条通知发送日志的完整信息，包含通知类型、接收用户、发送渠道、发送状态、失败原因（如有）、消息内容等。")
     @GetMapping("/{id}")
     public Result<NotificationLog> detail(@ApiParam("日志ID") @PathVariable Long id) {
         NotificationLog notificationLog = notificationLogService.getById(id);

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java
index 43516e4..f620a50 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java
@@ -19,7 +19,7 @@ public class OperationLogController {
 
     private final OperationLogService operationLogService;
 
-    @ApiOperation("操作日志分页查询")
+    @ApiOperation(value = "操作日志分页查询", notes = "查询管理员的操作记录，支持按模块、管理员、状态、时间范围筛选。记录包含请求参数、响应结果和耗时信息\n\n**关联字典**：\n- operation_log_status：操作状态（列表筛选+显示，0=成功/1=失败）")
     @GetMapping
     public Result<PageResult<OperationLog>> list(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -32,7 +32,8 @@ public class OperationLogController {
         return Result.success(operationLogService.queryPage(page, pageSize, module, adminId, status, startTime, endTime));
     }
 
-    @ApiOperation("操作日志详情")
+    @ApiOperation(value = "操作日志详情",
+            notes = "返回单条操作日志的完整信息，包含操作模块、操作描述、请求参数、响应结果、操作耗时、操作人信息、IP地址等。")
     @GetMapping("/{id}")
     public Result<OperationLog> detail(@ApiParam("日志ID") @PathVariable Long id) {
         OperationLog log = operationLogService.getById(id);

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java
index e70ae11..ffc059f 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java
@@ -17,7 +17,7 @@ public class RedisMonitorController {
 
     private final RedisMonitorService redisMonitorService;
 
-    @ApiOperation("Redis实时监控数据")
+    @ApiOperation(value = "Redis实时监控数据", notes = "返回Redis实时状态：内存使用量、连接数、Key数量、命中率、每秒命令数等核心指标")
     @GetMapping
     public Result<Map<String, Object>> overview() {
         return Result.success(redisMonitorService.getOverview());

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java
index 5d642cb..9f32297 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java
@@ -18,19 +18,19 @@ public class RocketMqMonitorController {
 
     private final RocketMqMonitorService rocketMqMonitorService;
 
-    @ApiOperation("RocketMQ概览")
+    @ApiOperation(value = "RocketMQ概览", notes = "返回RocketMQ集群状态：Broker状态、Topic数量、消息积压量、生产者/消费者连接数等核心指标")
     @GetMapping
     public Result<Map<String, Object>> overview() {
         return Result.success(rocketMqMonitorService.getOverview());
     }
 
-    @ApiOperation("Topic统计")
+    @ApiOperation(value = "Topic统计", notes = "返回各Topic的消息量、最新偏移量和消费进度等信息")
     @GetMapping("/topics")
     public Result<List<Map<String, Object>>> topicStats() {
         return Result.success(rocketMqMonitorService.getTopicStats());
     }
 
-    @ApiOperation("消费者组统计")
+    @ApiOperation(value = "消费者组统计", notes = "返回各消费者组的消费进度、积压量和在线消费者实例信息")
     @GetMapping("/consumer-groups")
     public Result<List<Map<String, Object>>> consumerGroupStats() {
         return Result.success(rocketMqMonitorService.getConsumerGroupStats());

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java` (M)

diff --git a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java
index 63d09ef..11e5509 100644
--- a/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java
+++ b/hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java
@@ -18,7 +18,7 @@ public class ServiceMonitorController {
 
     private final ServiceMonitorService serviceMonitorService;
 
-    @ApiOperation("微服务列表和健康状态")
+    @ApiOperation(value = "微服务列表和健康状态", notes = "从Nacos注册中心获取所有微服务的实例列表和健康状态，包含IP、端口、注册时间和健康检查结果")
     @GetMapping
     public Result<List<Map<String, Object>>> list() {
         return Result.success(serviceMonitorService.getServiceList());

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java
index f7f787c..da96036 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java
@@ -22,7 +22,8 @@ public class MpActivityController {
     private final MpResourceFeignClient resourceFeignClient;
     private final ResourceMapService resourceMapService;
 
-    @ApiOperation("活动列表")
+    @ApiOperation(value = "活动列表",
+            notes = "分页查询已上架的活动列表，支持关键词和分类筛选。聚合层透传resource-service的活动数据给小程序前端。")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listActivities(
             @ApiParam("关键词") @RequestParam(required = false) String keyword,
@@ -37,7 +38,8 @@ public class MpActivityController {
         return resourceFeignClient.listActivities(query);
     }
 
-    @ApiOperation("活动详情")
+    @ApiOperation(value = "活动详情",
+            notes = "获取活动完整信息（含图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。")
     @GetMapping("/{activityId}")
     public Result<Map<String, Object>> getActivityDetail(@ApiParam("活动ID") @PathVariable Long activityId) {
         Result<Map<String, Object>> result = resourceFeignClient.getActivityDetail(activityId);

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java
index 9023792..61ad359 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java
@@ -18,7 +18,7 @@ public class MpBadgeController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("获取徽章数据")
+    @ApiOperation(value = "获取徽章数据", notes = "返回用户的徽章统计（未读消息数、待办事项数等），用于「我的」页面角标展示")
     @GetMapping
     public Result<Map<String, Object>> getBadges(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java
index 6089f32..df4d3dd 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java
@@ -23,7 +23,8 @@ public class MpBannerController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("获取当前生效的轮播图列表")
+    @ApiOperation(value = "获取当前生效的轮播图列表",
+            notes = "返回当前处于有效期内的轮播图，按排序值排列。用于小程序首页顶部轮播展示，透传自user-service。")
     @GetMapping("/active")
     public Result<List<Map<String, Object>>> listActiveBanners() {
         return userFeignClient.listActiveBanners();

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java
index be29a79..84ec777 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java
@@ -22,13 +22,15 @@ public class MpConfigController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("获取所有非敏感前端配置")
+    @ApiOperation(value = "获取所有非敏感前端配置",
+            notes = "返回所有非SECRET类型的前端配置项（如主题色、客服电话、版本号等）。不含敏感配置，可安全传输给小程序端。")
     @GetMapping
     public Result<List<Map<String, Object>>> listPublicConfigs() {
         return userFeignClient.listAllFrontendConfigs();
     }
 
-    @ApiOperation("按分组获取非敏感前端配置")
+    @ApiOperation(value = "按分组获取非敏感前端配置",
+            notes = "按配置分组获取前端配置项，如UI分组、功能开关分组等。用于小程序按需加载特定分组的配置。")
     @GetMapping("/group/{group}")
     public Result<List<Map<String, Object>>> listPublicConfigsByGroup(
             @ApiParam("配置分组") @PathVariable String group) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java
index 4e34f66..c5b60cb 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java
@@ -20,7 +20,7 @@ public class MpContractController {
 
     private final MpContractFeignClient contractFeignClient;
 
-    @ApiOperation("合同列表")
+    @ApiOperation(value = "合同列表", notes = "**关联字典（BFF透传）**：\n- contract_status：合同状态（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listContracts(
             HttpServletRequest request,
@@ -31,7 +31,7 @@ public class MpContractController {
         return contractFeignClient.listContracts(userId, status, page, pageSize);
     }
 
-    @ApiOperation(value = "合同详情", notes = "返回合同基本信息、签署状态、出行人签署详情及合同文件下载链接")
+    @ApiOperation(value = "合同详情", notes = "返回合同基本信息、签署状态、出行人签署详情及合同文件下载链接\n\n**关联字典（BFF透传）**：\n- contract_status：合同状态（显示）")
     @GetMapping("/{id}")
     public Result<Map<String, Object>> getContractDetail(
             HttpServletRequest request,
@@ -40,7 +40,7 @@ public class MpContractController {
         return contractFeignClient.getContractDetail(id, userId);
     }
 
-    @ApiOperation(value = "按订单查合同", notes = "返回订单关联的最新有效合同（非作废）")
+    @ApiOperation(value = "按订单查合同", notes = "返回订单关联的最新有效合同（非作废）\n\n**关联字典（BFF透传）**：\n- contract_status：合同状态（显示）")
     @GetMapping("/by-order/{orderId}")
     public Result<Map<String, Object>> getContractByOrder(
             HttpServletRequest request,
@@ -49,7 +49,7 @@ public class MpContractController {
         return contractFeignClient.getContractByOrder(orderId, userId);
     }
 
-    @ApiOperation(value = "按订单查所有合同", notes = "返回订单关联的所有有效合同（TOUR+INSURANCE各一条）")
+    @ApiOperation(value = "按订单查所有合同", notes = "返回订单关联的所有有效合同（TOUR+INSURANCE各一条）\n\n**关联字典（BFF透传）**：\n- contract_status：合同状态（显示）")
     @GetMapping("/by-order/{orderId}/all")
     public Result<java.util.List<Map<String, Object>>> getContractsByOrder(
             HttpServletRequest request,
@@ -58,7 +58,8 @@ public class MpContractController {
         return contractFeignClient.getContractsByOrder(orderId, userId);
     }
 
-    @ApiOperation("重新发送合同签署短信")
+    @ApiOperation(value = "重新发送合同签署短信",
+            notes = "重新向出行人发送合同签署短信通知，适用于出行人未收到短信或短信过期的场景。\n\n**权限**：需登录。")
     @PostMapping("/{contractId}/resend-sms")
     public Result<Boolean> resendContractSms(
             @ApiParam("合同ID") @PathVariable Long contractId,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java
index ae62fb8..01d0115 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java
@@ -22,7 +22,8 @@ public class MpDesignerController {
     private final MpUserFeignClient userFeignClient;
     private final DesignerAggregationService designerAggregationService;
 
-    @ApiOperation("定制师列表(含真实产品数和评分，综合排序)")
+    @ApiOperation(value = "定制师列表(含真实产品数和评分，综合排序)",
+            notes = "获取定制师列表，聚合层会补充每个定制师的真实产品数量和评价评分。按综合排序（评分>路线数>咨询人数），用于小程序定制师推荐页。")
     @SuppressWarnings("unchecked")
     @GetMapping
     public Result<List<Map<String, Object>>> listDesigners(
@@ -37,7 +38,8 @@ public class MpDesignerController {
         return result;
     }
 
-    @ApiOperation("推荐定制师(综合排序第一名)")
+    @ApiOperation(value = "推荐定制师(综合排序第一名)",
+            notes = "获取综合排序排名第一的定制师信息（含产品数和评分），用于首页推荐定制师卡片展示。")
     @GetMapping("/featured")
     public Result<Map<String, Object>> getFeaturedDesigner() {
         // Fetch all designers, enrich and sort, return top one
@@ -74,7 +76,8 @@ public class MpDesignerController {
         try { return Integer.parseInt(obj.toString()); } catch (NumberFormatException e) { return 0; }
     }
 
-    @ApiOperation("定制师详情(含产品数量和评分)")
+    @ApiOperation(value = "定制师详情(含产品数量和评分)",
+            notes = "获取定制师完整个人信息，聚合层会补充该定制师的已发布产品数量和综合评分，用于定制师个人主页展示。")
     @GetMapping("/{id}")
     public Result<Map<String, Object>> getDesignerDetail(@ApiParam("定制师ID") @PathVariable Long id) {
         Map<String, Object> data = designerAggregationService.getDesignerDetailWithStats(id);
@@ -84,7 +87,7 @@ public class MpDesignerController {
         return Result.success(data);
     }
 
-    @ApiOperation("定制师已发布产品列表")
+    @ApiOperation(value = "定制师已发布产品列表", notes = "**关联字典（BFF透传）**：\n- product_type：产品类型（显示）")
     @GetMapping("/{id}/products")
     public Result<PageResult<Map<String, Object>>> getDesignerProducts(
             @ApiParam("定制师ID") @PathVariable Long id,
@@ -93,7 +96,7 @@ public class MpDesignerController {
         return designerAggregationService.getDesignerProducts(id, page, pageSize);
     }
 
-    @ApiOperation("定制师产品评价列表")
+    @ApiOperation(value = "定制师产品评价列表", notes = "**关联字典（BFF透传）**：\n- rating_level：评价等级（显示）")
     @GetMapping("/{id}/reviews")
     public Result<PageResult<Map<String, Object>>> getDesignerReviews(
             @ApiParam("定制师ID") @PathVariable Long id,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java
index b57cfd7..e689361 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java
@@ -23,7 +23,7 @@ public class MpDictController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("获取所有字典数据")
+    @ApiOperation(value = "获取所有字典数据", notes = "获取系统全部字典数据（按字典类型分组），用于小程序端的下拉选项、枚举映射等。建议前端缓存此数据")
     @GetMapping("/all")
     public Result<List<Map<String, Object>>> getAllDict() {
         return userFeignClient.getAllDict();

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java
index ba1fcaa..5aa4cfc 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java
@@ -9,6 +9,7 @@ import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import javax.servlet.http.HttpServletRequest;
+import java.util.Map;
 
 @Api(tags = "C端 - 探索接口")
 @RestController
@@ -18,9 +19,10 @@ public class MpExploreController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("探索列表")
+    @ApiOperation(value = "探索列表",
+            notes = "获取已启用的探索分类列表（图文攻略内容），支持综合/最新/最热排序，分页返回。用于小程序探索频道首页瀑布流展示。")
     @GetMapping("/list")
-    public Result<?> list(
+    public Result<Map<String, Object>> list(
             @ApiParam("排序方式：comprehensive/newest/hottest") @RequestParam(defaultValue = "comprehensive") String sortType,
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
             @ApiParam("每页条数") @RequestParam(defaultValue = "20") int pageSize) {
@@ -29,7 +31,7 @@ public class MpExploreController {
 
     @ApiOperation(value = "探索详情", notes = "自动增加浏览量，已登录时返回点赞/收藏状态")
     @GetMapping("/{id}")
-    public Result<?> detail(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
+    public Result<Map<String, Object>> detail(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
         // optional auth: userId may be null if not logged in
         Long userId = null;
         String userIdHeader = request.getHeader("X-User-Id");
@@ -42,22 +44,25 @@ public class MpExploreController {
         return userFeignClient.getExploreCategoryDetail(id, userId);
     }
 
-    @ApiOperation("浏览+1")
+    @ApiOperation(value = "浏览+1",
+            notes = "增加探索内容的浏览计数。前端进入探索详情页时调用，无需登录。")
     @PostMapping("/{id}/view")
-    public Result<?> view(@ApiParam("探索分类ID") @PathVariable Long id) {
+    public Result<Void> view(@ApiParam("探索分类ID") @PathVariable Long id) {
         return userFeignClient.incrementExploreViewCount(id);
     }
 
-    @ApiOperation("切换点赞")
+    @ApiOperation(value = "切换点赞",
+            notes = "对探索内容点赞/取消点赞，返回当前点赞状态（true=已点赞）。\n\n**权限**：需登录。")
     @PostMapping("/{id}/like")
-    public Result<?> toggleLike(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
+    public Result<Boolean> toggleLike(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.toggleExploreLike(id, userId);
     }
 
-    @ApiOperation("切换收藏")
+    @ApiOperation(value = "切换收藏",
+            notes = "对探索内容收藏/取消收藏，返回当前收藏状态（true=已收藏）。收藏后可在'我的收藏'中查看。\n\n**权限**：需登录。")
     @PostMapping("/{id}/favorite")
-    public Result<?> toggleFavorite(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
+    public Result<Boolean> toggleFavorite(@ApiParam("探索分类ID") @PathVariable Long id, HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.toggleExploreFavorite(id, userId);
     }

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java
index 94c53e4..d596692 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java
@@ -27,7 +27,7 @@ public class MpFavoriteController {
     private final MpUserFeignClient userFeignClient;
     private final FavoriteAggregationService favoriteAggregationService;
 
-    @ApiOperation("添加收藏")
+    @ApiOperation(value = "添加收藏", notes = "将产品/景区/餐厅/活动加入收藏。同一目标重复收藏会返回已有收藏记录")
     @PostMapping
     public Result<Map<String, Object>> addFavorite(HttpServletRequest request,
                                                     @Valid @RequestBody MpFavoriteRequest body) {
@@ -38,7 +38,8 @@ public class MpFavoriteController {
         return userFeignClient.addFavorite(userId, map);
     }
 
-    @ApiOperation("收藏列表（含资源摘要）")
+    @ApiOperation(value = "收藏列表（含资源摘要）",
+            notes = "分页查询收藏列表，聚合层会补充每个收藏项对应资源的摘要信息（名称、封面图、价格等）。支持按目标类型筛选。\n\n**权限**：需登录。\n\n**关联字典**：\n- favorite_resource_type：收藏资源类型（PRODUCT/SCENIC/RESTAURANT/ACTIVITY）")
     @GetMapping
     public Result<PageResult<FavoriteItemVO>> listFavorites(HttpServletRequest request,
                                                             @ApiParam("目标类型筛选（字典：favorite_resource_type）：PRODUCT/SCENIC/RESTAURANT/ACTIVITY")
@@ -49,7 +50,8 @@ public class MpFavoriteController {
         return Result.success(favoriteAggregationService.listFavorites(userId, targetType, page, pageSize));
     }
 
-    @ApiOperation("检查是否已收藏")
+    @ApiOperation(value = "检查是否已收藏",
+            notes = "检查当前用户是否已收藏指定资源，用于详情页收藏按钮状态显示。\n\n**权限**：需登录。")
     @GetMapping("/check")
     public Result<Boolean> checkFavorite(HttpServletRequest request,
                                           @ApiParam("目标类型（字典：favorite_resource_type）") @RequestParam String targetType,
@@ -58,7 +60,8 @@ public class MpFavoriteController {
         return userFeignClient.checkFavorite(userId, targetType, targetId);
     }
 
-    @ApiOperation("批量删除收藏")
+    @ApiOperation(value = "批量删除收藏",
+            notes = "批量删除多条收藏记录，传入收藏记录ID列表。用于收藏管理页面的批量操作。\n\n**权限**：需登录，仅能删除自己的收藏。")
     @DeleteMapping("/batch")
     public Result<Void> batchDeleteFavorites(HttpServletRequest request,
                                               @ApiParam("收藏ID列表") @RequestBody List<Long> ids) {
@@ -66,7 +69,8 @@ public class MpFavoriteController {
         return userFeignClient.batchDeleteFavorites(userId, ids);
     }
 
-    @ApiOperation("按目标取消收藏")
+    @ApiOperation(value = "按目标取消收藏",
+            notes = "通过目标类型+目标ID取消收藏，适用于详情页点击取消收藏的场景（不需要知道收藏记录ID）。\n\n**权限**：需登录。")
     @DeleteMapping("/by-target")
     public Result<Void> deleteFavoriteByTarget(HttpServletRequest request,
                                                 @ApiParam("目标类型") @RequestParam String targetType,
@@ -75,7 +79,8 @@ public class MpFavoriteController {
         return userFeignClient.deleteFavoriteByTarget(userId, targetType, targetId);
     }
 
-    @ApiOperation("取消收藏")
+    @ApiOperation(value = "取消收藏",
+            notes = "通过收藏记录ID取消收藏，适用于收藏列表页的删除操作。\n\n**权限**：需登录，仅能删除自己的收藏。")
     @DeleteMapping("/{id}")
     public Result<Void> deleteFavorite(HttpServletRequest request,
                                         @ApiParam("收藏记录ID") @PathVariable Long id) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java
index c25ed9b..ab02f01 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java
@@ -26,7 +26,7 @@ public class MpFootprintController {
     private final MpUserFeignClient userFeignClient;
     private final FootprintAggregationService footprintAggregationService;
 
-    @ApiOperation("记录足迹")
+    @ApiOperation(value = "记录足迹", notes = "记录用户浏览资源的足迹，同一资源重复浏览会更新浏览时间而非新增记录")
     @PostMapping
     public Result<Map<String, Object>> addFootprint(HttpServletRequest request,
                                                      @RequestBody MpFootprintAddRequest body) {
@@ -37,7 +37,8 @@ public class MpFootprintController {
         return userFeignClient.addFootprint(userId, map);
     }
 
-    @ApiOperation("足迹列表（含资源摘要）")
+    @ApiOperation(value = "足迹列表（含资源摘要）",
+            notes = "分页查询浏览足迹列表，聚合层会补充每条足迹对应资源的摘要信息（名称、封面图等）。支持按资源类型筛选，按浏览时间倒序。\n\n**权限**：需登录。")
     @GetMapping
     public Result<PageResult<FootprintItemVO>> listFootprints(HttpServletRequest request,
                                                                @ApiParam("资源类型筛选：PRODUCT/SCENIC/RESTAURANT/ACTIVITY") @RequestParam(required = false) String resourceType,
@@ -47,14 +48,16 @@ public class MpFootprintController {
         return Result.success(footprintAggregationService.listFootprints(userId, resourceType, page, pageSize));
     }
 
-    @ApiOperation("删除足迹")
+    @ApiOperation(value = "删除足迹",
+            notes = "删除单条浏览足迹记录。\n\n**权限**：需登录，仅能删除自己的足迹。")
     @DeleteMapping("/{id}")
     public Result<Void> deleteFootprint(HttpServletRequest request, @ApiParam("足迹ID") @PathVariable Long id) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.deleteFootprint(userId, id);
     }
 
-    @ApiOperation("批量删除足迹")
+    @ApiOperation(value = "批量删除足迹",
+            notes = "批量删除多条浏览足迹记录，传入足迹ID列表。用于足迹管理页面的批量清理。\n\n**权限**：需登录，仅能删除自己的足迹。")
     @DeleteMapping("/batch")
     public Result<Void> batchDeleteFootprints(HttpServletRequest request,
                                                @ApiParam("足迹ID列表") @RequestBody List<Long> ids) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java
index 8e7cdc5..0c6487f 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java
@@ -18,7 +18,7 @@ public class MpHomeController {
 
     private final HomeAggregationService homeAggregationService;
 
-    @ApiOperation(value = "首页数据", notes = "聚合流程：并行获取推荐产品列表+产品线列表+轮播图 → Redis缓存5分钟 → 返回聚合数据")
+    @ApiOperation(value = "首页数据", notes = "聚合流程：并行获取推荐产品列表+产品线列表+轮播图 → Redis缓存5分钟 → 返回聚合数据\n\n**关联字典（BFF透传）**：\n- product_type：产品类型（产品卡片显示）\n- product_status：产品状态（透传自product-service）")
     @GetMapping
     public Result<HomeDataVO> getHomeData() {
         return Result.success(homeAggregationService.getHomeData());

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java
index d820bba..2d649e1 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java
@@ -22,7 +22,8 @@ public class MpHotelController {
     private final MpResourceFeignClient resourceFeignClient;
     private final ResourceMapService resourceMapService;
 
-    @ApiOperation("酒店列表")
+    @ApiOperation(value = "酒店列表",
+            notes = "分页查询已上架的酒店列表，支持按关键词、城市、星级筛选。聚合层透传resource-service的酒店数据。")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listHotels(
             @ApiParam("关键词") @RequestParam(required = false) String keyword,
@@ -39,7 +40,8 @@ public class MpHotelController {
         return resourceFeignClient.listHotels(query);
     }
 
-    @ApiOperation("酒店详情")
+    @ApiOperation(value = "酒店详情",
+            notes = "获取酒店完整信息（含房型列表、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。")
     @GetMapping("/{hotelId}")
     public Result<Map<String, Object>> getHotelDetail(@ApiParam("酒店ID") @PathVariable Long hotelId) {
         Result<Map<String, Object>> result = resourceFeignClient.getHotelDetail(hotelId);

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java
index 3941bc4..d1403a0 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java
@@ -18,7 +18,7 @@ public class MpInsuranceController {
 
     private final MpInsuranceFeignClient insuranceFeignClient;
 
-    @ApiOperation(value = "获取订单所有保单PDF", notes = "合并所有出行人的有效保单为一个PDF，返回base64")
+    @ApiOperation(value = "获取订单所有保单PDF", notes = "合并所有出行人的有效保单为一个PDF，返回base64\n\n**关联字典（BFF透传）**：\n- insurance_status：保险状态（返回字段）")
     @GetMapping("/policy-pdf/{orderId}")
     public Result<Map<String, Object>> getPolicyPdf(
             @ApiParam("订单ID") @PathVariable Long orderId) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java
index bda90ad..a42a662 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java
@@ -31,7 +31,7 @@ public class MpInvoiceController {
         return orderFeignClient.applyInvoice(userId, body);
     }
 
-    @ApiOperation("发票详情")
+    @ApiOperation(value = "发票详情", notes = "获取发票的完整信息，包含开票状态、发票抬头、税号、金额、电子发票文件链接等")
     @GetMapping("/{id}")
     public Result<Map<String, Object>> getInvoiceDetail(@ApiParam("发票ID") @PathVariable Long id,
                                                          HttpServletRequest request) {
@@ -39,7 +39,7 @@ public class MpInvoiceController {
         return orderFeignClient.getInvoiceDetail(id, userId);
     }
 
-    @ApiOperation("通过订单ID查询发票")
+    @ApiOperation(value = "通过订单ID查询发票", notes = "查询指定订单的发票信息，如果订单未开票则返回null")
     @GetMapping("/order/{orderId}")
     public Result<Map<String, Object>> getInvoiceByOrderId(@ApiParam("订单ID") @PathVariable Long orderId,
                                                             HttpServletRequest request) {
@@ -47,7 +47,7 @@ public class MpInvoiceController {
         return orderFeignClient.getInvoiceByOrderId(orderId, userId);
     }
 
-    @ApiOperation("发票换开")
+    @ApiOperation(value = "发票换开", notes = "对已开发票申请换开（修改抬头/税号等），原发票作废后重新开具新发票")
     @PostMapping("/{invoiceId}/reissue")
     public Result<Map<String, Object>> reissueInvoice(
             @ApiParam("发票ID") @PathVariable Long invoiceId,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java
index d60be9e..c8d50b5 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java
@@ -57,7 +57,8 @@ public class MpLikeController {
         return result;
     }
 
-    @ApiOperation("检查是否已点赞")
+    @ApiOperation(value = "检查是否已点赞",
+            notes = "检查当前用户是否已对指定目标点赞，用于前端点赞按钮状态展示。\n\n**权限**：需登录。")
     @GetMapping("/{targetType}/{targetId}/check")
     public Result<Boolean> checkLike(
             @ApiParam("目标类型") @PathVariable String targetType,
@@ -67,7 +68,8 @@ public class MpLikeController {
         return userFeignClient.checkLikeStatus(targetType.toUpperCase(), targetId, userId);
     }
 
-    @ApiOperation("批量检查点赞状态")
+    @ApiOperation(value = "批量检查点赞状态",
+            notes = "批量检查当前用户是否已对多个目标点赞，返回已点赞的目标ID列表。用于列表页批量展示点赞状态。\n\n**权限**：需登录。")
     @PostMapping("/{targetType}/batch-check")
     public Result<List<String>> batchCheckLiked(
             @ApiParam("目标类型") @PathVariable String targetType,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java
index bc4abe0..e1f7fa6 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java
@@ -37,7 +37,7 @@ public class MpOrderController {
         return orderFeignClient.createOrder(userId, body);
     }
 
-    @ApiOperation("订单列表")
+    @ApiOperation(value = "订单列表", notes = "分页查询当前用户的订单列表，支持按状态筛选。返回订单摘要信息（不含详细出行人信息）\n\n**关联字典（BFF透传）**：\n- order_status：订单状态（列表筛选+显示）\n- product_type：产品类型（订单卡片显示）")
     @GetMapping("/list")
     public Result<PageResult<MpOrderListItemVO>> listOrders(HttpServletRequest request,
                                                               @ApiParam("状态") @RequestParam(required = false) String status,
@@ -51,7 +51,7 @@ public class MpOrderController {
         return orderFeignClient.listOrders(userId, query);
     }
 
-    @ApiOperation("订单详情")
+    @ApiOperation(value = "订单详情", notes = "获取订单完整信息，包含产品快照、出行人列表、支付信息、合同状态等\n\n**关联字典（BFF透传）**：\n- order_status：订单状态（显示）\n- product_type：产品类型（显示）\n- contract_status：合同状态（显示）")
     @GetMapping("/{orderId}")
     public Result<MpOrderDetailVO> getOrder(HttpServletRequest request,
                                               @ApiParam("订单ID") @PathVariable Long orderId) {
@@ -86,9 +86,10 @@ public class MpOrderController {
         return orderFeignClient.cancelOrder(userId, orderId, body != null ? body : new MpCancelOrderRequest());
     }
 
-    @ApiOperation("通过联系人手机号+姓名查找订单（无需登录）")
+    @ApiOperation(value = "通过联系人手机号+姓名查找订单（无需登录）",
+            notes = "无需登录即可查询。用于管理员代下单场景：管理员创建订单后，用户通过联系人手机号+姓名查找订单并绑定到自己账号。仅返回尚未绑定用户(userId=NULL)的订单。")
     @GetMapping("/lookup")
-    public Result<?> lookupByContact(@ApiParam("联系人手机号") @RequestParam String contactPhone,
+    public Result<List<Map<String, Object>>> lookupByContact(@ApiParam("联系人手机号") @RequestParam String contactPhone,
                                      @ApiParam("联系人姓名") @RequestParam String contactName) {
         return orderFeignClient.lookupByContact(contactPhone, contactName);
     }
@@ -101,7 +102,7 @@ public class MpOrderController {
         return orderFeignClient.bindByContact(userId, body);
     }
 
-    @ApiOperation("同意解锁订单")
+    @ApiOperation(value = "同意解锁订单", notes = "用户同意管理员的修改请求，解除订单锁定状态，允许管理员继续修改订单")
     @PostMapping("/{orderId}/approve-unlock")
     public Result<Void> approveUnlock(HttpServletRequest request,
                                        @ApiParam("订单ID") @PathVariable Long orderId) {
@@ -116,7 +117,7 @@ public class MpOrderController {
         return orderFeignClient.getUpcomingDepartures(userId);
     }
 
-    @ApiOperation("各状态订单数量")
+    @ApiOperation(value = "各状态订单数量", notes = "统计当前用户各状态的订单数量，用于「我的」页面的订单状态角标展示\n\n**关联字典（BFF透传）**：\n- order_status：订单状态（状态分类统计）")
     @GetMapping("/count")
     public Result<Map<String, Object>> countByStatus(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java
index 6ddf62a..274102d 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java
@@ -21,7 +21,7 @@ public class MpPaymentController {
     private final MpPaymentFeignClient paymentFeignClient;
 
     @PostMapping("/prepay")
-    @ApiOperation(value = "发起支付", notes = "支付流程：选择支付方式(JSAPI/H5) → 调用微信支付API → 返回支付参数 → 前端调起微信支付")
+    @ApiOperation(value = "发起支付", notes = "支付流程：选择支付方式(JSAPI/H5) → 调用微信支付API → 返回支付参数 → 前端调起微信支付\n\n**关联字典（BFF透传）**：\n- payment_status：支付状态（返回字段）")
     public Result<Map<String, Object>> prepay(
             HttpServletRequest httpRequest,
             @ApiParam("支付请求体") @RequestBody MpPaymentPrepayRequest request) {
@@ -30,7 +30,7 @@ public class MpPaymentController {
     }
 
     @GetMapping("/status/{orderId}")
-    @ApiOperation("查询支付状态")
+    @ApiOperation(value = "查询支付状态", notes = "**关联字典（BFF透传）**：\n- payment_status：支付状态（显示）")
     public Result<Map<String, Object>> getStatus(@ApiParam("订单ID") @PathVariable Long orderId,
                                                   HttpServletRequest httpRequest) {
         Long userId = (Long) httpRequest.getAttribute("userId");
@@ -38,8 +38,8 @@ public class MpPaymentController {
     }
 
     @GetMapping("/transactions/{orderId}")
-    @ApiOperation("订单交易记录列表")
-    public Result<Object> listTransactions(@ApiParam("订单ID") @PathVariable Long orderId,
+    @ApiOperation(value = "订单交易记录列表", notes = "**关联字典（BFF透传）**：\n- payment_status：支付状态（显示）")
+    public Result<java.util.List<Map<String, Object>>> listTransactions(@ApiParam("订单ID") @PathVariable Long orderId,
                                             HttpServletRequest httpRequest) {
         Long userId = (Long) httpRequest.getAttribute("userId");
         return paymentFeignClient.listTransactions(userId, orderId);

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java
index 6aa9542..1aa236f 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java
@@ -34,7 +34,7 @@ public class MpProductController {
     private final MpOrderFeignClient orderFeignClient;
     private final ProductAggregationService productAggregationService;
 
-    @ApiOperation("产品列表")
+    @ApiOperation(value = "产品列表", notes = "分页查询已上架产品，支持按关键词、产品类型(CORE/ROUTE/CUSTOM/GROUP)、季节、天数、目的地、产品线筛选和排序\n\n**关联字典（BFF透传）**：\n- product_type：产品类型（列表筛选+显示）\n- product_status：产品状态（透传自product-service）")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listProducts(
             @ApiParam("搜索关键词") @RequestParam(required = false) String keyword,
@@ -63,7 +63,7 @@ public class MpProductController {
         return productFeignClient.listProducts(query);
     }
 
-    @ApiOperation(value = "产品详情（聚合收藏状态）", notes = "聚合流程：获取产品详情 → 并行查询收藏状态 → 异步记录足迹 → 返回聚合数据。支持未登录访问（不返回收藏状态）")
+    @ApiOperation(value = "产品详情（聚合收藏状态）", notes = "聚合流程：获取产品详情 → 并行查询收藏状态 → 异步记录足迹 → 返回聚合数据。支持未登录访问（不返回收藏状态）\n\n**关联字典（BFF透传）**：\n- product_type：产品类型（显示）\n- product_status：产品状态（透传自product-service）")
     @GetMapping("/{productId}")
     public Result<MpProductDetailVO> getProduct(HttpServletRequest request,
                                                  @ApiParam("产品ID") @PathVariable Long productId) {
@@ -256,7 +256,7 @@ public class MpProductController {
         }
     }
 
-    @ApiOperation("产品线列表")
+    @ApiOperation(value = "产品线列表", notes = "返回所有已启用的产品线，用于小程序首页或筛选栏展示")
     @GetMapping("/lines")
     public Result<List<Map<String, Object>>> listLines() {
         return productFeignClient.listActiveLines();
@@ -284,7 +284,7 @@ public class MpProductController {
         return productFeignClient.listBatchCombos(batchId);
     }
 
-    @ApiOperation("价格日历")
+    @ApiOperation(value = "价格日历", notes = "返回产品指定日期范围内的每日价格，用于日历组件展示。不传日期时默认返回未来一个月")
     @GetMapping("/{productId}/price-calendar")
     public Result<List<Map<String, Object>>> getPriceCalendar(
             @ApiParam("产品ID") @PathVariable Long productId,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java
index 5a72099..71890d6 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java
@@ -32,7 +32,7 @@ public class MpRefundController {
         return orderFeignClient.refundPreview(userId, orderId);
     }
 
-    @ApiOperation("退款原因列表")
+    @ApiOperation(value = "退款原因列表", notes = "返回系统预设的退款原因选项，用于退款申请页面的原因选择")
     @GetMapping("/refund-reasons")
     public Result<List<MpRefundReasonVO>> listRefundReasons() {
         return orderFeignClient.listRefundReasons();
@@ -48,7 +48,7 @@ public class MpRefundController {
         return orderFeignClient.applyRefund(userId, userName, orderId, body);
     }
 
-    @ApiOperation("退款申请详情")
+    @ApiOperation(value = "退款申请详情", notes = "获取退款申请的完整信息，包含审核状态、退款金额、退款进度和操作记录\n\n**关联字典（BFF透传）**：\n- order_status：订单状态（显示）\n- payment_status：支付/退款状态（显示）")
     @GetMapping("/refund/{applicationId}")
     public Result<MpRefundDetailVO> getRefundDetail(@ApiParam("退款申请ID") @PathVariable Long applicationId,
                                                        HttpServletRequest request) {
@@ -56,7 +56,7 @@ public class MpRefundController {
         return orderFeignClient.getRefundDetail(userId, applicationId);
     }
 
-    @ApiOperation("根据订单ID获取最新退款详情")
+    @ApiOperation(value = "根据订单ID获取最新退款详情", notes = "查询订单关联的最新一条退款申请详情，无退款记录时返回null\n\n**关联字典（BFF透传）**：\n- order_status：订单状态（显示）\n- payment_status：支付/退款状态（显示）")
     @GetMapping("/{orderId}/refund-detail")
     public Result<MpRefundDetailVO> getRefundDetailByOrder(@ApiParam("订单ID") @PathVariable String orderId,
                                                               HttpServletRequest request) {
@@ -84,7 +84,7 @@ public class MpRefundController {
         return orderFeignClient.refundAppeal(userId, applicationId, body);
     }
 
-    @ApiOperation("撤回退款申请")
+    @ApiOperation(value = "撤回退款申请", notes = "仅PENDING状态的退款申请可撤回，撤回后订单恢复到原状态")
     @PostMapping("/refund/{applicationId}/cancel")
     public Result<Void> cancelRefund(@ApiParam("退款申请ID") @PathVariable Long applicationId,
                                       HttpServletRequest request) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java
index 4b75e9b..38fa21b 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java
@@ -22,7 +22,8 @@ public class MpRestaurantController {
     private final MpResourceFeignClient resourceFeignClient;
     private final ResourceMapService resourceMapService;
 
-    @ApiOperation("餐厅列表")
+    @ApiOperation(value = "餐厅列表",
+            notes = "分页查询已上架的餐厅列表，支持按关键词和城市筛选。聚合层透传resource-service的餐厅数据。")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listRestaurants(
             @ApiParam("关键词") @RequestParam(required = false) String keyword,
@@ -37,7 +38,8 @@ public class MpRestaurantController {
         return resourceFeignClient.listRestaurants(query);
     }
 
-    @ApiOperation("餐厅详情")
+    @ApiOperation(value = "餐厅详情",
+            notes = "获取餐厅完整信息（含菜品、图文详情等），自动注入静态地图图片URL用于详情页地图展示。")
     @GetMapping("/{restaurantId}")
     public Result<Map<String, Object>> getRestaurantDetail(@ApiParam("餐厅ID") @PathVariable Long restaurantId) {
         Result<Map<String, Object>> result = resourceFeignClient.getRestaurantDetail(restaurantId);

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java
index 1f44df4..1cf55b2 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java
@@ -55,7 +55,7 @@ public class MpReviewController {
         return Result.success(categories);
     }
 
-    @ApiOperation(value = "创建评价", notes = "评价流程：订单完成后 → 查询可评价目标列表 → 对每个目标(酒店/景区/活动等)提交评价 → 自动内容审核 → 审核通过后公开展示")
+    @ApiOperation(value = "创建评价", notes = "评价流程：订单完成后 → 查询可评价目标列表 → 对每个目标(酒店/景区/活动等)提交评价 → 自动内容审核 → 审核通过后公开展示\n\n**关联字典（BFF透传）**：\n- review_status：评价审核状态（返回字段）\n- rating_level：评价等级（返回字段）")
     @PostMapping("/create")
     public Result<Map<String, Object>> createReview(@ApiParam("评价请求体") @RequestBody MpReviewCreateRequest body,
                                                      HttpServletRequest request) {
@@ -65,7 +65,7 @@ public class MpReviewController {
         return reviewFeignClient.createReview(body, userId);
     }
 
-    @ApiOperation("我的评价列表")
+    @ApiOperation(value = "我的评价列表", notes = "**关联字典（BFF透传）**：\n- review_status：评价审核状态（显示）\n- rating_level：评价等级（显示）")
     @GetMapping("/my")
     public Result<PageResult<Map<String, Object>>> getMyReviews(
             @ApiParam("页码") @RequestParam(defaultValue = "1") Integer page,
@@ -75,7 +75,7 @@ public class MpReviewController {
         return reviewFeignClient.getMyReviews(page, pageSize, userId);
     }
 
-    @ApiOperation(value = "关键词搜索评价(公开)", notes = "按关键词搜索已通过的评价内容，支持按目标类型和目标ID筛选")
+    @ApiOperation(value = "关键词搜索评价(公开)", notes = "按关键词搜索已通过的评价内容，支持按目标类型和目标ID筛选\n\n**关联字典（BFF透传）**：\n- rating_level：评价等级（显示）")
     @GetMapping("/search")
     public Result<PageResult<Map<String, Object>>> searchReviews(
             @ApiParam(value = "搜索关键词", required = true) @RequestParam String keyword,
@@ -86,7 +86,7 @@ public class MpReviewController {
         return reviewFeignClient.searchReviews(keyword, targetType, targetId, page, pageSize);
     }
 
-    @ApiOperation("某目标的已通过评价(公开)")
+    @ApiOperation(value = "某目标的已通过评价(公开)", notes = "**关联字典（BFF透传）**：\n- rating_level：评价等级（筛选+显示）")
     @GetMapping("/target")
     public Result<PageResult<Map<String, Object>>> getTargetReviews(
             @ApiParam("目标类型") @RequestParam String targetType,
@@ -102,7 +102,7 @@ public class MpReviewController {
         return reviewFeignClient.getTargetReviews(targetType, targetId, ratingLevel, hasImage, hasVideo, page, pageSize);
     }
 
-    @ApiOperation(value = "按产品ID查看评价列表", notes = "返回评价列表+统计数据，支持好中差评/有图/有视频筛选")
+    @ApiOperation(value = "按产品ID查看评价列表", notes = "返回评价列表+统计数据，支持好中差评/有图/有视频筛选\n\n**关联字典（BFF透传）**：\n- rating_level：评价等级（筛选+显示）")
     @GetMapping("/product/{productId}")
     public Result<Map<String, Object>> getProductReviews(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -144,7 +144,8 @@ public class MpReviewController {
         return reviewFeignClient.getProductHighlights(productId);
     }
 
-    @ApiOperation("评价统计(平均分、数量)")
+    @ApiOperation(value = "评价统计(平均分、数量)",
+            notes = "获取指定目标的评价统计数据（平均评分、总评价数等），用于详情页评价区域展示。产品showReview关闭时返回空统计。")
     @GetMapping("/stats")
     public Result<Map<String, Object>> getTargetStats(
             @ApiParam("目标类型") @RequestParam String targetType,
@@ -174,21 +175,23 @@ public class MpReviewController {
         return true; // 查询失败时默认显示
     }
 
-    @ApiOperation(value = "精选评价列表(公开)", notes = "无需登录，返回精选评价数组，用于评价浏览页")
+    @ApiOperation(value = "精选评价列表(公开)", notes = "无需登录，返回精选评价数组，用于评价浏览页\n\n**关联字典（BFF透传）**：\n- rating_level：评价等级（显示）")
     @GetMapping("/featured")
     public Result<List<Map<String, Object>>> getFeaturedReviews(
             @ApiParam("数量限制") @RequestParam(defaultValue = "50") Integer limit) {
         return reviewFeignClient.getFeaturedReviews(limit);
     }
 
-    @ApiOperation("检查订单是否已评价")
+    @ApiOperation(value = "检查订单是否已评价",
+            notes = "检查指定订单是否已提交评价，用于订单详情页决定是否显示'去评价'按钮。")
     @GetMapping("/order/{orderId}/reviewed")
     public Result<Boolean> isOrderReviewed(
             @ApiParam("订单ID") @PathVariable Long orderId) {
         return reviewFeignClient.isOrderReviewed(orderId);
     }
 
-    @ApiOperation("订单可评价目标列表")
+    @ApiOperation(value = "订单可评价目标列表",
+            notes = "返回订单中可评价的资源目标列表（景区/酒店/活动等），用于评价页面展示可评价项。已评价的目标不会重复出现。\n\n**权限**：需登录。")
     @GetMapping("/order/{orderId}/reviewable-targets")
     public Result<List<Map<String, Object>>> getReviewableTargets(
             @ApiParam("订单ID") @PathVariable Long orderId, HttpServletRequest request) {
@@ -196,7 +199,8 @@ public class MpReviewController {
         return reviewFeignClient.getReviewableTargets(orderId, userId);
     }
 
-    @ApiOperation("点赞/取消点赞评价")
+    @ApiOperation(value = "点赞/取消点赞评价",
+            notes = "对评价进行点赞或取消点赞操作，返回当前点赞状态和点赞总数。\n\n**权限**：需登录。")
     @PostMapping("/{reviewId}/like")
     public Result<Map<String, Object>> toggleLike(
             @ApiParam("评价ID") @PathVariable Long reviewId, HttpServletRequest request) {
@@ -204,7 +208,8 @@ public class MpReviewController {
         return reviewFeignClient.toggleLike(reviewId, userId);
     }
 
-    @ApiOperation("检查是否已点赞")
+    @ApiOperation(value = "检查是否已点赞",
+            notes = "检查当前用户是否已点赞指定评价，用于评价列表/详情的点赞按钮状态展示。\n\n**权限**：需登录。")
     @GetMapping("/{reviewId}/like/check")
     public Result<Boolean> checkLiked(
             @ApiParam("评价ID") @PathVariable Long reviewId, HttpServletRequest request) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java
index 96a4529..8f59647 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java
@@ -27,7 +27,8 @@ public class MpScenicController {
     private final MpUserFeignClient userFeignClient;
     private final ResourceMapService resourceMapService;
 
-    @ApiOperation("景区列表")
+    @ApiOperation(value = "景区列表",
+            notes = "分页查询已上架的景区列表，支持按关键词和城市筛选。聚合层透传resource-service的景区数据。")
     @GetMapping("/list")
     public Result<PageResult<Map<String, Object>>> listScenic(
             @ApiParam("关键词") @RequestParam(required = false) String keyword,
@@ -42,7 +43,8 @@ public class MpScenicController {
         return resourceFeignClient.listScenic(query);
     }
 
-    @ApiOperation("景区详情")
+    @ApiOperation(value = "景区详情",
+            notes = "获取景区完整信息（含季节素材、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。")
     @GetMapping("/{scenicId}")
     public Result<Map<String, Object>> getScenicDetail(@ApiParam("景区ID") @PathVariable Long scenicId) {
         Result<Map<String, Object>> result = resourceFeignClient.getScenicDetail(scenicId);
@@ -52,7 +54,8 @@ public class MpScenicController {
         return result;
     }
 
-    @ApiOperation("附近景区（地理+探索分类聚合）")
+    @ApiOperation(value = "附近景区（地理+探索分类聚合）",
+            notes = "聚合两个数据源：1.基于经纬度的地理位置附近景区（resource-service）；2.探索分类关联的景区（user-service）。去重合并后返回，用于景区详情页底部'附近推荐'展示。")
     @GetMapping("/{scenicId}/nearby")
     public Result<List<Map<String, Object>>> getNearbyScenic(
             @ApiParam("景区ID") @PathVariable Long scenicId,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java
index 7a2362a..689c544 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java
@@ -20,7 +20,7 @@ public class MpSearchController {
 
     private final MpProductFeignClient productFeignClient;
 
-    @ApiOperation("搜索产品")
+    @ApiOperation(value = "搜索产品", notes = "按关键词搜索已上架产品（匹配产品名称和描述），支持按产品类型进一步筛选\n\n**关联字典（BFF透传）**：\n- product_type：产品类型（筛选+显示）")
     @GetMapping
     public Result<PageResult<Map<String, Object>>> search(
             @ApiParam("搜索关键词") @RequestParam String keyword,

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java
index 8831fd0..4f8f4d9 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java
@@ -22,7 +22,7 @@ public class MpTravelerController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("添加出行人")
+    @ApiOperation(value = "添加出行人", notes = "添加常用出行人信息（姓名/证件/联系方式等），下单时可快速选择。单个用户最多50个出行人")
     @PostMapping
     public Result<Map<String, Object>> addTraveler(HttpServletRequest request,
                                                     @RequestBody MpTravelerRequest body) {
@@ -31,21 +31,23 @@ public class MpTravelerController {
         return userFeignClient.addTraveler(userId, map);
     }
 
-    @ApiOperation("出行人列表")
+    @ApiOperation(value = "出行人列表", notes = "返回当前用户的所有出行人列表。如果用户已完善实名信息，列表中会自动包含一条「本人」虚拟记录(travelerId=0)")
     @GetMapping
     public Result<List<Map<String, Object>>> listTravelers(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.listTravelers(userId);
     }
 
-    @ApiOperation("出行人详情")
+    @ApiOperation(value = "出行人详情",
+            notes = "获取单个出行人的完整信息（姓名、证件信息、联系方式等）。\n\n**权限**：需登录，仅能查看自己的出行人。")
     @GetMapping("/{id}")
     public Result<Map<String, Object>> getTraveler(HttpServletRequest request, @ApiParam("出行人ID") @PathVariable Long id) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.getTraveler(userId, id);
     }
 
-    @ApiOperation("更新出行人")
+    @ApiOperation(value = "更新出行人",
+            notes = "修改出行人信息，支持部分更新（只传需要修改的字段）。已关联订单的出行人修改不影响历史订单记录。\n\n**权限**：需登录。")
     @PutMapping("/{id}")
     public Result<Map<String, Object>> updateTraveler(HttpServletRequest request,
                                                        @ApiParam("出行人ID") @PathVariable Long id,
@@ -55,14 +57,15 @@ public class MpTravelerController {
         return userFeignClient.updateTraveler(userId, id, map);
     }
 
-    @ApiOperation("删除出行人")
+    @ApiOperation(value = "删除出行人",
+            notes = "删除常用出行人记录。默认出行人不可删除，需先取消默认后再删除。\n\n**权限**：需登录。")
     @DeleteMapping("/{id}")
     public Result<Void> deleteTraveler(HttpServletRequest request, @ApiParam("出行人ID") @PathVariable Long id) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.deleteTraveler(userId, id);
     }
 
-    @ApiOperation("设为默认出行人")
+    @ApiOperation(value = "设为默认出行人", notes = "设为默认出行人后，下单时自动作为第一个出行人。每个用户只能有一个默认出行人")
     @PutMapping("/{id}/default")
     public Result<Void> setDefaultTraveler(HttpServletRequest request, @ApiParam("出行人ID") @PathVariable Long id) {
         Long userId = (Long) request.getAttribute("userId");

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java
index 5247c6f..9870345 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java
@@ -22,14 +22,14 @@ public class MpTripController {
     private final MpOrderFeignClient orderFeignClient;
     private final WeatherService weatherService;
 
-    @ApiOperation(value = "行程列表", notes = "获取当前登录用户的行程列表（已确认及进行中的订单对应的行程）")
+    @ApiOperation(value = "行程列表", notes = "获取当前登录用户的行程列表（已确认及进行中的订单对应的行程）\n\n**关联字典（BFF透传）**：\n- order_status：订单/行程状态（显示）")
     @GetMapping("/list")
     public Result<List<Map<String, Object>>> getTripList(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return orderFeignClient.getTripList(userId);
     }
 
-    @ApiOperation(value = "行程详情", notes = "获取订单对应的行程详情，含每日行程节点信息（景点/酒店/餐厅等）")
+    @ApiOperation(value = "行程详情", notes = "获取订单对应的行程详情，含每日行程节点信息（景点/酒店/餐厅等）\n\n**关联字典（BFF透传）**：\n- order_status：订单/行程状态（显示）")
     @GetMapping("/{orderId}")
     public Result<Map<String, Object>> getTripDetail(HttpServletRequest request,
                                                       @ApiParam(value = "订单ID", required = true) @PathVariable Long orderId) {
@@ -37,7 +37,7 @@ public class MpTripController {
         return orderFeignClient.getTripDetail(userId, orderId);
     }
 
-    @ApiOperation(value = "今日行程", notes = "获取今日行程（如果有正在进行中的行程），无行程时data为null")
+    @ApiOperation(value = "今日行程", notes = "获取今日行程（如果有正在进行中的行程），无行程时data为null\n\n**关联字典（BFF透传）**：\n- order_status：订单/行程状态（显示）")
     @GetMapping("/today")
     public Result<Map<String, Object>> getTodayTrip(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java
index 26146f8..249591a 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java
@@ -20,7 +20,7 @@ public class MpUserController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("发送短信验证码")
+    @ApiOperation(value = "发送短信验证码", notes = "向指定手机号发送登录验证码，有效期5分钟，60秒内不可重复发送")
     @PostMapping("/sms/send")
     public Result<Void> sendSmsCode(@RequestBody MpSmsSendRequest request) {
         Map<String, String> map = new java.util.HashMap<>();
@@ -45,14 +45,14 @@ public class MpUserController {
         return userFeignClient.login(map);
     }
 
-    @ApiOperation("获取用户信息")
+    @ApiOperation(value = "获取用户信息", notes = "获取当前登录用户的个人资料，包含头像、昵称、手机号、实名信息等")
     @GetMapping("/profile")
     public Result<Map<String, Object>> getProfile(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.getProfile(userId);
     }
 
-    @ApiOperation("更新用户信息")
+    @ApiOperation(value = "更新用户信息", notes = "更新当前用户的个人资料，支持部分更新（只传需要修改的字段）。首次完善资料时realName为必填")
     @PutMapping("/profile")
     public Result<Map<String, Object>> updateProfile(HttpServletRequest request,
                                                       @RequestBody MpUserProfileUpdateRequest body) {
@@ -69,7 +69,8 @@ public class MpUserController {
         return userFeignClient.updateProfile(userId, map);
     }
 
-    @ApiOperation("用户登出")
+    @ApiOperation(value = "用户登出",
+            notes = "清除用户登录状态和服务端缓存的令牌信息。登出后需重新登录获取新令牌。\n\n**权限**：需登录。")
     @PostMapping("/logout")
     public Result<Void> logout(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java
index 9341450..592fba5 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java
@@ -19,21 +19,21 @@ public class MpWeatherController {
 
     private final MpOrderFeignClient orderFeignClient;
 
-    @ApiOperation("获取订单行程天气")
+    @ApiOperation(value = "获取订单行程天气", notes = "根据订单行程中的目的地城市，批量查询每日天气信息，用于行程详情页展示")
     @GetMapping("/itinerary/{orderId}")
     public Result<List<Map<String, Object>>> getItineraryWeather(
             @ApiParam("订单ID") @PathVariable Long orderId) {
         return orderFeignClient.getItineraryWeather(orderId);
     }
 
-    @ApiOperation("获取指定城市实况天气")
+    @ApiOperation(value = "获取指定城市实况天气", notes = "通过高德天气API查询指定城市的实时天气（温度、湿度、风向等）")
     @GetMapping("/live")
     public Result<Map<String, Object>> getLiveWeather(
             @ApiParam("城市名称") @RequestParam String city) {
         return orderFeignClient.getLiveWeather(city);
     }
 
-    @ApiOperation("获取指定城市天气预报")
+    @ApiOperation(value = "获取指定城市天气预报", notes = "通过高德天气API查询指定城市未来3天的天气预报信息")
     @GetMapping("/forecast")
     public Result<Map<String, Object>> getForecastWeather(
             @ApiParam("城市名称") @RequestParam String city) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java
index 26fe4ac..c70bd36 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java
@@ -20,13 +20,15 @@ public class MpWikiController {
 
     private final MpWikiFeignClient wikiFeignClient;
 
-    @ApiOperation("攻略分类列表")
+    @ApiOperation(value = "攻略分类列表",
+            notes = "获取所有已启用的攻略分类，按排序值排列。用于小程序攻略频道的分类导航展示。")
     @GetMapping("/categories")
     public Result<List<Map<String, Object>>> listCategories() {
         return wikiFeignClient.listEnabledCategories();
     }
 
-    @ApiOperation("分类文章列表")
+    @ApiOperation(value = "分类文章列表",
+            notes = "分页查询指定攻略分类下已发布的文章列表，按发布时间倒序排列。用于攻略分类详情页。")
     @GetMapping("/category/{categoryId}/articles")
     public Result<PageResult<Map<String, Object>>> listCategoryArticles(
             @ApiParam("攻略分类ID") @PathVariable Long categoryId,
@@ -35,13 +37,14 @@ public class MpWikiController {
         return wikiFeignClient.listCategoryArticles(categoryId, page, pageSize);
     }
 
-    @ApiOperation("文章详情")
+    @ApiOperation(value = "文章详情", notes = "**关联字典（BFF透传）**：\n- wiki_status：文章状态（返回字段）")
     @GetMapping("/article/{articleId}")
     public Result<Map<String, Object>> getArticle(@ApiParam("文章ID") @PathVariable Long articleId) {
         return wikiFeignClient.getArticle(articleId);
     }
 
-    @ApiOperation("推荐文章列表")
+    @ApiOperation(value = "推荐文章列表",
+            notes = "获取编辑推荐的攻略文章列表（按推荐权重排序），用于首页或攻略频道的推荐位展示。")
     @GetMapping("/recommend-articles")
     public Result<List<Map<String, Object>>> listRecommendArticles(
             @ApiParam("返回条数") @RequestParam(defaultValue = "10") Integer limit) {

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java
index f9abab8..d9d2416 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java
@@ -21,14 +21,14 @@ public class MpWishController {
 
     private final MpUserFeignClient userFeignClient;
 
-    @ApiOperation("心愿单列表")
+    @ApiOperation(value = "心愿单列表", notes = "返回当前用户的心愿单列表，按创建时间倒序排列")
     @GetMapping
     public Result<List<Map<String, Object>>> listWishes(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
         return userFeignClient.listWishes(userId);
     }
 
-    @ApiOperation("创建心愿")
+    @ApiOperation(value = "创建心愿", notes = "创建旅行心愿，描述想去的地方和时间偏好，定制师可据此推荐产品")
     @PostMapping
     public Result<Map<String, Object>> createWish(@ApiParam("心愿请求体") @RequestBody MpWishCreateRequest body,
                                                    HttpServletRequest request) {

`hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignClient.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignClient.java b/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignClient.java
index b722dd7..d30f577 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignClient.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignClient.java
@@ -19,6 +19,6 @@ public interface MpPaymentFeignClient {
                                            @PathVariable("orderId") Long orderId);
 
     @GetMapping("/internal/payment/transactions/{orderId}")
-    Result<Object> listTransactions(@RequestParam("userId") Long userId,
+    Result<java.util.List<java.util.Map<String, Object>>> listTransactions(@RequestParam("userId") Long userId,
                                      @PathVariable("orderId") Long orderId);
 }

`hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignFallbackFactory.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignFallbackFactory.java b/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignFallbackFactory.java
index 48fc044..28c303b 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignFallbackFactory.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpPaymentFeignFallbackFactory.java
@@ -27,7 +27,7 @@ public class MpPaymentFeignFallbackFactory implements FallbackFactory<MpPaymentF
             }
 
             @Override
-            public Result<Object> listTransactions(Long userId, Long orderId) {
+            public Result<java.util.List<java.util.Map<String, Object>>> listTransactions(Long userId, Long orderId) {
                 return Result.error("支付服务不可用，请稍后重试");
             }
         };

`hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignClient.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignClient.java b/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignClient.java
index 3ccc5b3..9927e9a 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignClient.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignClient.java
@@ -189,36 +189,36 @@ public interface MpUserFeignClient {
     // ==================== Explore ====================
 
     @GetMapping("/internal/mp/explore/active")
-    Result<?> listActiveExploreCategories(
+    Result<Map<String, Object>> listActiveExploreCategories(
             @RequestParam(defaultValue = "comprehensive") String sortType,
             @RequestParam(defaultValue = "1") int page,
             @RequestParam(defaultValue = "20") int pageSize);
 
     @GetMapping("/internal/mp/explore/{id}")
-    Result<?> getExploreCategoryDetail(
+    Result<Map<String, Object>> getExploreCategoryDetail(
             @PathVariable("id") Long id,
             @RequestHeader(value = "X-User-Id", required = false) Long userId);
 
     @PostMapping("/internal/mp/explore/{id}/view")
-    Result<?> incrementExploreViewCount(@PathVariable("id") Long id);
+    Result<Void> incrementExploreViewCount(@PathVariable("id") Long id);
 
     @PostMapping("/internal/mp/explore/{id}/like")
-    Result<?> toggleExploreLike(
+    Result<Boolean> toggleExploreLike(
             @PathVariable("id") Long id,
             @RequestHeader("X-User-Id") Long userId);
 
     @GetMapping("/internal/mp/explore/{id}/like/check")
-    Result<?> checkExploreLike(
+    Result<Boolean> checkExploreLike(
             @PathVariable("id") Long id,
             @RequestHeader("X-User-Id") Long userId);
 
     @PostMapping("/internal/mp/explore/{id}/favorite")
-    Result<?> toggleExploreFavorite(
+    Result<Boolean> toggleExploreFavorite(
             @PathVariable("id") Long id,
             @RequestHeader("X-User-Id") Long userId);
 
     @GetMapping("/internal/mp/explore/{id}/favorite/check")
-    Result<?> checkExploreFavorite(
+    Result<Boolean> checkExploreFavorite(
             @PathVariable("id") Long id,
             @RequestHeader("X-User-Id") Long userId);

`hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignFallbackFactory.java` (M)

diff --git a/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignFallbackFactory.java b/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignFallbackFactory.java
index c9b9a72..517c974 100644
--- a/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignFallbackFactory.java
+++ b/hl-mp-service/src/main/java/com/hulalv/mp/feign/MpUserFeignFallbackFactory.java
@@ -215,37 +215,37 @@ public class MpUserFeignFallbackFactory implements FallbackFactory<MpUserFeignCl
             }
 
             @Override
-            public Result<?> listActiveExploreCategories(String sortType, int page, int pageSize) {
+            public Result<Map<String, Object>> listActiveExploreCategories(String sortType, int page, int pageSize) {
                 return Result.error("用户服务不可用，请稍后重试");
             }
 
             @Override
-            public Result<?> getExploreCategoryDetail(Long id, Long userId) {
+            public Result<Map<String, Object>> getExploreCategoryDetail(Long id, Long userId) {
                 return Result.error("用户服务不可用，请稍后重试");
             }
 
             @Override
-            public Result<?> incrementExploreViewCount(Long id) {
+            public Result<Void> incrementExploreViewCount(Long id) {
                 return Result.error("用户服务不可用，请稍后重试");
             }
 
             @Override
-            public Result<?> toggleExploreLike(Long id, Long userId) {
+            public Result<Boolean> toggleExploreLike(Long id, Long userId) {
                 return Result.error("用户服务不可用，请稍后重试");
             }
 
             @Override
-            public Result<?> checkExploreLike(Long id, Long userId) {
+            public Result<Boolean> checkExploreLike(Long id, Long userId) {
                 return Result.error("用户服务不可用，请稍后重试");
             }
 
             @Override
-            public Result<?> toggleExploreFavorite(Long id, Long userId) {
+            public Result<Boolean> toggleExploreFavorite(Long id, Long userId) {
                 return Result.error("用户服务不可用，请稍后重试");
             }
 
             @Override
-            public Result<?> checkExploreFavorite(Long id, Long userId) {
+            public Result<Boolean> checkExploreFavorite(Long id, Long userId) {
                 return Result.error("用户服务不可用，请稍后重试");
             }

`hl-order-service/src/main/java/com/hulalv/order/config/Knife4jConfig.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/config/Knife4jConfig.java b/hl-order-service/src/main/java/com/hulalv/order/config/Knife4jConfig.java
index 6e9ee90..1e90666 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/config/Knife4jConfig.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/config/Knife4jConfig.java
@@ -39,17 +39,6 @@ public class Knife4jConfig {
                 .build();
     }
 
-    @Bean
-    public Docket internalApi() {
-        return new Docket(DocumentationType.SWAGGER_2)
-                .groupName("3.3 内部接口(Feign)")
-                .apiInfo(apiInfo())
-                .select()
-                .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
-                .paths(PathSelectors.ant("/internal/**"))
-                .build();
-    }
-
     private ApiInfo apiInfo() {
         return new ApiInfoBuilder()
                 .title("呼籁旅行 - 订单服务 API")

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java
index 9b8e419..dce7686 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java
@@ -28,7 +28,7 @@ public class AdminAlbumController {
 
     // ==================== 文件夹管理 ====================
 
-    @ApiOperation("创建相册文件夹")
+    @ApiOperation(value = "创建相册文件夹", notes = "为订单创建旅行相册文件夹（如'第一天风景'、'合影'等），用于组织旅途照片/视频")
     @PostMapping("/{orderId}/album/folder")
     public Result<AlbumFolderVO> createFolder(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -38,7 +38,7 @@ public class AdminAlbumController {
         return Result.success(albumService.createFolder(orderId, request, adminId));
     }
 
-    @ApiOperation("编辑相册文件夹")
+    @ApiOperation(value = "编辑相册文件夹", notes = "修改文件夹名称或描述。仅创建者或超级管理员可操作")
     @PutMapping("/album/folder/{folderId}")
     public Result<AlbumFolderVO> updateFolder(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -49,7 +49,7 @@ public class AdminAlbumController {
         return Result.success(albumService.updateFolder(folderId, request, adminId, roleKey));
     }
 
-    @ApiOperation("删除相册文件夹")
+    @ApiOperation(value = "删除相册文件夹", notes = "删除文件夹及其下所有文件。仅创建者或超级管理员可操作。删除后C端用户不再可见")
     @DeleteMapping("/album/folder/{folderId}")
     public Result<Void> deleteFolder(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -60,7 +60,8 @@ public class AdminAlbumController {
         return Result.success(null);
     }
 
-    @ApiOperation("查询订单的文件夹列表")
+    @ApiOperation(value = "查询订单的文件夹列表",
+            notes = "获取指定订单的所有相册文件夹，含文件夹名称、描述、封面图、文件数量等信息。")
     @GetMapping("/{orderId}/album/folders")
     public Result<List<AlbumFolderVO>> listFolders(
             @ApiParam("订单ID") @PathVariable Long orderId) {
@@ -69,7 +70,11 @@ public class AdminAlbumController {
 
     // ==================== 文件管理 ====================
 
-    @ApiOperation("批量添加文件到文件夹")
+    @ApiOperation(value = "批量添加文件到文件夹", notes = "一次添加多个照片/视频到指定文件夹。文件需先通过文件服务上传获取OSS URL\n\n" +
+            "**关联字典**：\n" +
+            "- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频\n" +
+            "- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PostMapping("/album/folder/{folderId}/files")
     public Result<List<AlbumFileVO>> addFiles(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -80,7 +85,10 @@ public class AdminAlbumController {
         return Result.success(albumService.addFiles(folderId, request, adminId, roleKey));
     }
 
-    @ApiOperation("编辑文件信息")
+    @ApiOperation(value = "编辑文件信息", notes = "**关联字典**：\n" +
+            "- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频\n" +
+            "- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PutMapping("/album/file/{albumFileId}")
     public Result<AlbumFileVO> updateFile(
             @ApiParam("相册文件ID") @PathVariable Long albumFileId,
@@ -91,7 +99,8 @@ public class AdminAlbumController {
         return Result.success(albumService.updateFile(albumFileId, request, adminId, roleKey));
     }
 
-    @ApiOperation("删除文件")
+    @ApiOperation(value = "删除文件",
+            notes = "删除相册中的单个文件（照片/视频）。仅上传者或超级管理员可操作，删除后C端用户不再可见。")
     @DeleteMapping("/album/file/{albumFileId}")
     public Result<Void> deleteFile(
             @ApiParam("相册文件ID") @PathVariable Long albumFileId,
@@ -102,7 +111,10 @@ public class AdminAlbumController {
         return Result.success(null);
     }
 
-    @ApiOperation("查询文件夹下的文件列表")
+    @ApiOperation(value = "查询文件夹下的文件列表", notes = "**关联字典**：\n" +
+            "- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频\n" +
+            "- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @GetMapping("/album/folder/{folderId}/files")
     public Result<PageResult<AlbumFileVO>> listFiles(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -111,7 +123,8 @@ public class AdminAlbumController {
         return Result.success(albumService.listFiles(folderId, page, size));
     }
 
-    @ApiOperation("设置文件夹封面")
+    @ApiOperation(value = "设置文件夹封面",
+            notes = "将文件夹中的指定文件设为封面图，封面图会在文件夹列表中展示。仅上传者或超级管理员可操作。")
     @PutMapping("/album/folder/{folderId}/cover")
     public Result<Void> setCover(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -123,7 +136,11 @@ public class AdminAlbumController {
         return Result.success(null);
     }
 
-    @ApiOperation("我的上传（当前管理员上传的所有相册文件）")
+    @ApiOperation(value = "我的上传", notes = "查询当前管理员上传的所有相册文件（跨订单），方便管理自己上传的内容\n\n" +
+            "**关联字典**：\n" +
+            "- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频\n" +
+            "- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @GetMapping("/album/my-uploads")
     public Result<PageResult<AlbumFileVO>> listMyUploads(
             HttpServletRequest httpRequest,

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java
index 261c457..85b97c1 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java
@@ -31,7 +31,7 @@ public class AdminEarlyBirdController {
         }
     }
 
-    @ApiOperation("早鸟优惠计划列表")
+    @ApiOperation(value = "早鸟优惠计划列表", notes = "分页查询所有早鸟优惠计划。权限：仅超级管理员(SUPER_ADMIN)")
     @GetMapping("/list")
     public Result<PageResult<EarlyBirdPlanVO>> list(HttpServletRequest request,
                                                     @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -41,7 +41,7 @@ public class AdminEarlyBirdController {
         return Result.success(result);
     }
 
-    @ApiOperation("早鸟优惠计划详情")
+    @ApiOperation(value = "早鸟优惠计划详情", notes = "权限：仅超级管理员(SUPER_ADMIN)")
     @GetMapping("/{planId}")
     public Result<EarlyBirdPlanVO> detail(HttpServletRequest request,
                                           @ApiParam("早鸟计划ID") @PathVariable Long planId) {
@@ -50,7 +50,8 @@ public class AdminEarlyBirdController {
         return Result.success(vo);
     }
 
-    @ApiOperation("创建早鸟优惠计划")
+    @ApiOperation(value = "创建早鸟优惠计划", notes = "创建一个早鸟优惠计划，在指定日期范围内下单且满足最低人数条件的订单可享受优惠。\n" +
+            "下单时系统自动匹配最优的早鸟计划。权限：仅超级管理员(SUPER_ADMIN)")
     @PostMapping
     public Result<EarlyBirdPlanVO> create(HttpServletRequest request,
                                           @ApiParam("创建早鸟计划请求") @Valid @RequestBody EarlyBirdPlanRequest planRequest) {
@@ -61,7 +62,7 @@ public class AdminEarlyBirdController {
         return Result.success(vo);
     }
 
-    @ApiOperation("修改早鸟优惠计划")
+    @ApiOperation(value = "修改早鸟优惠计划", notes = "权限：仅超级管理员(SUPER_ADMIN)。修改不影响已下单的订单优惠")
     @PutMapping("/{planId}")
     public Result<Void> update(HttpServletRequest request,
                                @ApiParam("早鸟计划ID") @PathVariable Long planId,
@@ -71,7 +72,7 @@ public class AdminEarlyBirdController {
         return Result.success();
     }
 
-    @ApiOperation("删除早鸟优惠计划")
+    @ApiOperation(value = "删除早鸟优惠计划", notes = "权限：仅超级管理员(SUPER_ADMIN)。删除不影响已下单的订单优惠")
     @DeleteMapping("/{planId}")
     public Result<Void> delete(HttpServletRequest request,
                                @ApiParam("早鸟计划ID") @PathVariable Long planId) {
@@ -80,7 +81,7 @@ public class AdminEarlyBirdController {
         return Result.success();
     }
 
-    @ApiOperation("启用/禁用早鸟优惠计划")
+    @ApiOperation(value = "启用/禁用早鸟优惠计划", notes = "禁用后该计划不再参与自动匹配。权限：仅超级管理员(SUPER_ADMIN)")
     @PutMapping("/{planId}/toggle")
     public Result<Void> toggle(HttpServletRequest request,
                                @ApiParam("早鸟计划ID") @PathVariable Long planId,

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java
index de26a0f..d79934d 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java
@@ -27,7 +27,8 @@ public class AdminOrderConfigController {
     @Value("${order.expiry.redis-key:order:config:expiry-minutes}")
     private String expiryRedisKey;
 
-    @ApiOperation("获取订单过期配置")
+    @ApiOperation(value = "获取订单过期配置", notes = "获取当前的订单未支付自动过期时间（分钟）。\n" +
+            "返回当前值、默认值和配置来源（redis=已自定义, default=使用默认值）")
     @GetMapping("/expiry-minutes")
     public Result<Map<String, Object>> getExpiryMinutes() {
         String val = stringRedisTemplate.opsForValue().get(expiryRedisKey);
@@ -45,7 +46,8 @@ public class AdminOrderConfigController {
         ));
     }
 
-    @ApiOperation("设置订单过期时间（分钟）")
+    @ApiOperation(value = "设置订单过期时间（分钟）", notes = "修改订单未支付自动取消的等待时间。存储在Redis中，即时生效。\n" +
+            "仅影响新创建的订单，已有订单的过期时间不变")
     @PutMapping("/expiry-minutes")
     public Result<Void> setExpiryMinutes(@ApiParam("修改订单过期时间请求") @Valid @RequestBody UpdateExpiryMinutesRequest expiryRequest) {
         stringRedisTemplate.opsForValue().set(expiryRedisKey, String.valueOf(expiryRequest.getMinutes()));

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java
index e7f09ce..72bdfc8 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java
@@ -47,7 +47,18 @@ public class AdminOrderController {
     private static final String ORDER_CREATE_DEDUP = "order:admin:create:dedup:";
 
     @ApiOperation(value = "创建订单（定制师代下单）", notes = "创建订单流程：选择产品 → 填写联系人和出行人 → 系统计算报价 → 生成订单(PENDING_PAY状态)\n\n" +
-            "权限：CUSTOM产品仅创建者可下单，CORE/ROUTE产品所有管理员可下单")
+            "权限：CUSTOM产品仅创建者可下单，CORE/ROUTE产品所有管理员可下单\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 productType → 字典：product_type（产品类型）\n" +
+            "- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 请求参数 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）\n" +
+            "- 返回字段 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 返回字段 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 返回字段 travelers[].gender → 字典：gender（性别）")
     @PostMapping("/create")
     public Result<OrderDetailVO> createOrder(HttpServletRequest request,
                                              @ApiParam("创建订单请求") @Valid @RequestBody AdminCreateOrderRequest createRequest) {
@@ -69,21 +80,41 @@ public class AdminOrderController {
         }
     }
 
-    @ApiOperation("报价预览")
+    @ApiOperation(value = "报价预览", notes = "根据产品、出发日期、人数组合实时计算报价。\n" +
+            "返回各资源明细价格和合计金额，前端据此展示报价清单。\n\n" +
+            "注意：报价仅供参考，最终价格以创建订单时为准（价格日历可能变动）")
     @PostMapping("/quote")
     public Result<Map<String, Object>> quotePreview(@ApiParam("报价预览请求") @Valid @RequestBody QuotePreviewRequest quoteRequest) {
         Map<String, Object> result = orderService.quotePreview(quoteRequest);
         return Result.success(result);
     }
 
-    @ApiOperation("订单列表")
+    @ApiOperation(value = "订单列表", notes = "支持按关键词（订单号/联系人/产品名）、状态、内部流程状态、产品类型筛选。\n" +
+            "支持按创建时间/出发日期/总价排序。\n\n" +
+            "返回分页结果，包含订单基本信息、状态、支付信息和产品封面\n\n" +
+            "【关联字典】\n" +
+            "- 筛选参数 status → 字典：order_status（订单状态）\n" +
+            "- 筛选参数 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 筛选参数 productType → 字典：product_type（产品类型）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/list")
     public Result<PageResult<OrderListVO>> listOrders(@ApiParam("订单查询请求") AdminOrderQueryRequest request) {
         PageResult<OrderListVO> result = orderService.listAdminOrders(request);
         return Result.success(result);
     }
 
-    @ApiOperation("订单详情")
+    @ApiOperation(value = "订单详情", notes = "返回订单完整信息，包括：基本信息、产品快照、联系人、出行人列表、支付记录、优惠明细、时间线、内部流程状态等\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）\n" +
+            "- 返回字段 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 返回字段 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 返回字段 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 timeline[].action → 字典：order_timeline_action（订单操作类型）\n" +
+            "- 返回字段 todos[].todoType → 字典：order_todo_type（订单待办类型）")
     @GetMapping("/{orderId}")
     public Result<OrderDetailVO> getOrder(@ApiParam("订单ID") @PathVariable Long orderId) {
         OrderDetailVO detail = orderService.getAdminOrderDetail(orderId);
@@ -111,7 +142,9 @@ public class AdminOrderController {
             "- 旅行中 → 已完成\n" +
             "- 已完成 → 售后中\n" +
             "- 售后中 → 退款中\n" +
-            "- 退款中 → 已退款")
+            "- 退款中 → 已退款\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 status → 字典：order_status（订单状态）")
     @PutMapping("/{orderId}/status")
     public Result<Void> updateStatus(HttpServletRequest request,
                                         @ApiParam("订单ID") @PathVariable Long orderId,
@@ -134,7 +167,7 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("添加备注")
+    @ApiOperation(value = "添加备注", notes = "向订单时间线添加一条管理员备注。备注会记录操作人和时间，可用于内部沟通和订单跟踪")
     @PostMapping("/{orderId}/remark")
     public Result<Void> addRemark(HttpServletRequest request,
                                      @ApiParam("订单ID") @PathVariable Long orderId,
@@ -145,7 +178,8 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("修改定金金额")
+    @ApiOperation(value = "修改定金金额", notes = "修改订单的定金金额。仅待支付(PENDING_PAY)状态可修改。\n\n" +
+            "定金金额不能超过订单总价，修改后影响用户支付页面显示的应付金额")
     @PutMapping("/{orderId}/deposit")
     public Result<Void> updateDeposit(HttpServletRequest request,
                                       @ApiParam("订单ID") @PathVariable Long orderId,
@@ -156,7 +190,14 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("编辑订单")
+    @ApiOperation(value = "编辑订单", notes = "修改订单的联系人、人数、出发日期、售价、成本、备注等信息。\n" +
+            "仅传入需要修改的字段，未传入的字段不会被修改。\n\n" +
+            "如果提供了出行人列表(travelers)，将替换订单的全部出行人。\n" +
+            "已锁定的订单需先调用'申请修改'接口解锁后才能编辑\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 请求参数 travelers[].gender → 字典：gender（性别）")
     @PutMapping("/{orderId}")
     public Result<Void> editOrder(HttpServletRequest request,
                                   @ApiParam("订单ID") @PathVariable Long orderId,
@@ -167,7 +208,8 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("更新房间信息（仅房务管理员/超级管理员）")
+    @ApiOperation(value = "更新房间信息（仅房务管理员/超级管理员）",
+            notes = "更新订单的房间分配信息（房型、房间号、入住安排等）。\n\n**权限**：仅ROOM_MANAGER（房务管理员）或SUPER_ADMIN（超级管理员）可操作。")
     @PutMapping("/{orderId}/room-info")
     public Result<Void> updateRoomInfo(HttpServletRequest request,
                                        @ApiParam("订单ID") @PathVariable Long orderId,
@@ -183,7 +225,8 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("更新车辆信息（仅车务管理员/超级管理员）")
+    @ApiOperation(value = "更新车辆信息（仅车务管理员/超级管理员）",
+            notes = "更新订单的车辆分配信息（车型、车牌号、司机等）。\n\n**权限**：仅VEHICLE_MANAGER（车务管理员）或SUPER_ADMIN（超级管理员）可操作。")
     @PutMapping("/{orderId}/vehicle-info")
     public Result<Void> updateVehicleInfo(HttpServletRequest request,
                                           @ApiParam("订单ID") @PathVariable Long orderId,
@@ -210,7 +253,9 @@ public class AdminOrderController {
     }
 
     @ApiOperation(value = "推进内部流程", notes = "内部流程推进顺序：待配房(PENDING_ROOM) → 待配车(PENDING_VEHICLE) → 待核算(PENDING_FINANCE) → 就绪(READY)\n\n" +
-            "仅在订单状态为已确认(CONFIRMED)时有效，每次调用自动推进到下一步")
+            "仅在订单状态为已确认(CONFIRMED)时有效，每次调用自动推进到下一步\n\n" +
+            "【关联字典】\n" +
+            "- 涉及字段 processStatus → 字典：order_process_status（订单内部流程状态）")
     @PutMapping("/{orderId}/process-status")
     public Result<Void> advanceProcessStatus(HttpServletRequest request,
                                              @ApiParam("订单ID") @PathVariable Long orderId) {
@@ -220,7 +265,8 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("添加优惠项")
+    @ApiOperation(value = "添加优惠项", notes = "为订单添加手动优惠（如会员折扣、老客优惠等）。\n" +
+            "添加后系统自动重算订单应付金额。一个订单可添加多个优惠项")
     @PostMapping("/{orderId}/discount")
     public Result<OrderDiscount> addDiscount(HttpServletRequest request,
                                              @ApiParam("订单ID") @PathVariable Long orderId,
@@ -231,7 +277,7 @@ public class AdminOrderController {
         return Result.success(discount);
     }
 
-    @ApiOperation("修改优惠项")
+    @ApiOperation(value = "修改优惠项", notes = "修改已添加的优惠项名称或金额，修改后自动重算订单应付金额")
     @PutMapping("/{orderId}/discount/{discountId}")
     public Result<Void> updateDiscount(HttpServletRequest request,
                                        @ApiParam("订单ID") @PathVariable Long orderId,
@@ -243,7 +289,7 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("删除优惠项")
+    @ApiOperation(value = "删除优惠项", notes = "删除已添加的优惠项，删除后自动重算订单应付金额")
     @DeleteMapping("/{orderId}/discount/{discountId}")
     public Result<Void> removeDiscount(HttpServletRequest request,
                                        @ApiParam("订单ID") @PathVariable Long orderId,
@@ -296,7 +342,8 @@ public class AdminOrderController {
         return Result.success(diff);
     }
 
-    @ApiOperation("分配车辆信息")
+    @ApiOperation(value = "分配车辆信息", notes = "为订单分配具体的车辆和司机信息（车型、品牌、车牌号、司机姓名和电话）。\n" +
+            "分配后信息将展示在订单详情和C端行程中")
     @PutMapping("/{orderId}/vehicle-assignment")
     public Result<Void> assignVehicle(@ApiParam("订单ID") @PathVariable Long orderId,
                                       @RequestBody @Valid VehicleAssignmentRequest request) {
@@ -304,7 +351,8 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("分配酒店信息")
+    @ApiOperation(value = "分配酒店信息", notes = "按家庭为订单分配具体的酒店房间（酒店名称、房型、入住/退房日期）。\n" +
+            "每个家庭对应一条分配记录，分配后信息将展示在订单详情和C端行程中")
     @PutMapping("/{orderId}/hotel-assignment")
     public Result<Void> assignHotel(@ApiParam("订单ID") @PathVariable Long orderId,
                                      @RequestBody @Valid HotelAssignmentRequest request) {
@@ -312,7 +360,7 @@ public class AdminOrderController {
         return Result.success();
     }
 
-    @ApiOperation("设置尾款支付方式")
+    @ApiOperation(value = "设置尾款支付方式", notes = "设置订单尾款的支付方式。ONLINE=线上微信支付，OFFLINE=线下转账（需管理员手动记录尾款到账）")

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java
index 83ae39c..9ab5d5e 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java
@@ -31,7 +31,11 @@ public class AdminOrderItineraryController {
     private final OrderItineraryEditService itineraryEditService;
     private final OrderPriceDiffService priceDiffService;
 
-    @ApiOperation(value = "跳过节点", notes = "将行程中的某个节点标记为跳过（客户不去）")
+    @ApiOperation(value = "跳过节点", notes = "将行程中的某个节点标记为跳过（客户不去）\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PostMapping("/skip")
     public Result<OrderItineraryEdit> skipNode(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -43,7 +47,10 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.skipNode(orderId, request, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "恢复跳过的节点", notes = "取消跳过，恢复为正常状态")
+    @ApiOperation(value = "恢复跳过的节点", notes = "取消跳过，恢复为正常状态\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @DeleteMapping("/skip/{editId}")
     public Result<Void> unskipNode(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -58,7 +65,11 @@ public class AdminOrderItineraryController {
         return Result.success();
     }
 
-    @ApiOperation(value = "新增节点", notes = "在某一天的行程中新增一个节点")
+    @ApiOperation(value = "新增节点", notes = "在某一天的行程中新增一个节点\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PostMapping("/add")
     public Result<OrderItineraryEdit> addNode(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -76,7 +87,10 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.addNode(orderId, request, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "删除新增的节点", notes = "删除通过编辑新增的节点")
+    @ApiOperation(value = "删除新增的节点", notes = "删除通过编辑新增的节点\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @DeleteMapping("/add/{editId}")
     public Result<Void> removeAddedNode(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -91,7 +105,10 @@ public class AdminOrderItineraryController {
         return Result.success();
     }
 
-    @ApiOperation("获取合并后的行程（原始+编辑）")
+    @ApiOperation(value = "获取合并后的行程（原始+编辑）", notes = "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @GetMapping("/merged")
     public Result<List<Map<String, Object>>> getMergedItinerary(
             @ApiParam("订单ID") @PathVariable Long orderId) {
@@ -105,14 +122,19 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.getBalanceAdjustmentSummary(orderId));
     }
 
-    @ApiOperation("获取行程编辑记录列表")
+    @ApiOperation(value = "获取行程编辑记录列表", notes = "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @GetMapping("/edits")
     public Result<List<OrderItineraryEdit>> getEditList(
             @ApiParam("订单ID") @PathVariable Long orderId) {
         return Result.success(itineraryEditService.getEditList(orderId));
     }
 
-    @ApiOperation(value = "房型切换差价预览", notes = "预览房型切换的差价，不创建记录")
+    @ApiOperation(value = "房型切换差价预览", notes = "预览房型切换的差价，不创建记录\n\n" +
+            "**关联字典**：\n" +
+            "- resource_type（资源类型，返回字段resourceType）：HOTEL=酒店")
     @PostMapping("/room-type-change/preview")
     public Result<PriceDiffVO> previewRoomTypeChange(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -120,7 +142,11 @@ public class AdminOrderItineraryController {
         return Result.success(priceDiffService.previewRoomTypeDiff(orderId, request));
     }
 
-    @ApiOperation(value = "房型切换", notes = "执行房型切换，自动计算差价，创建待确认记录")
+    @ApiOperation(value = "房型切换", notes = "执行房型切换，自动计算差价，创建待确认记录\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：ROOM_CHANGE=房型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：HOTEL=酒店")
     @PostMapping("/room-type-change")
     public Result<OrderItineraryEdit> roomTypeChange(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -132,7 +158,9 @@ public class AdminOrderItineraryController {
         return Result.success(priceDiffService.executeRoomTypeChange(orderId, request, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "车型切换差价预览", notes = "预览车型切换的差价，不创建记录")
+    @ApiOperation(value = "车型切换差价预览", notes = "预览车型切换的差价，不创建记录\n\n" +
+            "**关联字典**：\n" +
+            "- resource_type（资源类型，返回字段resourceType）：VEHICLE=车辆")
     @PostMapping("/vehicle-type-change/preview")
     public Result<PriceDiffVO> previewVehicleTypeChange(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -140,7 +168,11 @@ public class AdminOrderItineraryController {
         return Result.success(priceDiffService.previewVehicleTypeDiff(orderId, request));
     }
 
-    @ApiOperation(value = "车型切换", notes = "执行车型切换，自动计算差价，创建待确认记录")
+    @ApiOperation(value = "车型切换", notes = "执行车型切换，自动计算差价，创建待确认记录\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：VEHICLE=车辆")
     @PostMapping("/vehicle-type-change")
     public Result<OrderItineraryEdit> vehicleTypeChange(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -152,7 +184,11 @@ public class AdminOrderItineraryController {
         return Result.success(priceDiffService.executeVehicleTypeChange(orderId, request, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "新增整天行程", notes = "在订单行程中新增一整天（含多个节点）")
+    @ApiOperation(value = "新增整天行程", notes = "在订单行程中新增一整天（含多个节点）\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：ADD_DAY=新增整天\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PostMapping("/add-day")
     public Result<List<OrderItineraryEdit>> addDay(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -164,7 +200,9 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.addDay(orderId, request, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "删除新增的整天行程", notes = "删除通过新增操作添加的整天行程及其所有子节点，已确认的天不允许删除")
+    @ApiOperation(value = "删除新增的整天行程", notes = "删除通过新增操作添加的整天行程及其所有子节点，已确认的天不允许删除\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @DeleteMapping("/day/{editId}")
     public Result<Void> removeDay(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -179,7 +217,11 @@ public class AdminOrderItineraryController {
         return Result.success();
     }
 
-    @ApiOperation(value = "修改编辑记录", notes = "修改待确认状态的编辑记录（如调整价格、名称等）")
+    @ApiOperation(value = "修改编辑记录", notes = "修改待确认状态的编辑记录（如调整价格、名称等）\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @PutMapping("/edit/{editId}")
     public Result<OrderItineraryEdit> updateEdit(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -192,7 +234,9 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.updateEdit(orderId, editId, updates, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "确认单条修改", notes = "确认一条待确认的行程编辑")
+    @ApiOperation(value = "确认单条修改", notes = "确认一条待确认的行程编辑\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @PostMapping("/confirm/{editId}")
     public Result<Void> confirmEdit(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -205,7 +249,9 @@ public class AdminOrderItineraryController {
         return Result.success();
     }
 
-    @ApiOperation(value = "批量确认所有待确认修改", notes = "确认该订单所有待确认的行程编辑")
+    @ApiOperation(value = "批量确认所有待确认修改", notes = "确认该订单所有待确认的行程编辑\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @PostMapping("/confirm-all")
     public Result<Integer> confirmAllPending(
             @ApiParam("订单ID") @PathVariable Long orderId,
@@ -216,7 +262,9 @@ public class AdminOrderItineraryController {
         return Result.success(itineraryEditService.confirmAllPending(orderId, adminId, adminName, roleKey));
     }
 
-    @ApiOperation(value = "撤回待确认的修改", notes = "软删除一条待确认的编辑记录")
+    @ApiOperation(value = "撤回待确认的修改", notes = "软删除一条待确认的编辑记录\n\n" +
+            "**关联字典**：\n" +
+            "- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认")
     @DeleteMapping("/pending/{editId}")
     public Result<Void> withdrawPendingEdit(
             @ApiParam("订单ID") @PathVariable Long orderId,

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java
index d7339d2..f708a7f 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java
@@ -29,14 +29,21 @@ public class AdminOrderTodoController {
     private final OrderService orderService;
     private final UserFeignClient userFeignClient;
 
-    @ApiOperation("获取订单待办列表")
+    @ApiOperation(value = "获取订单待办列表", notes = "返回指定订单的所有待办项（含已完成和未完成）。\n" +
+            "待办类型包括：配房、配车、签合同、购保险、核算等，随内部流程自动生成\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 todoType → 字典：order_todo_type（订单待办类型）")
     @GetMapping("/{orderId}/todos")
     public Result<List<OrderTodo>> getOrderTodos(@ApiParam("订单ID") @PathVariable Long orderId) {
         List<OrderTodo> todos = orderTodoService.listByOrderId(orderId);
         return Result.success(todos);
     }
 
-    @ApiOperation("完成待办")
+    @ApiOperation(value = "完成待办", notes = "将指定待办标记为已完成。\n" +
+            "需要对应角色权限：如配房待办需ROOM_MANAGER角色，配车待办需VEHICLE_MANAGER角色。\n\n" +
+            "完成后系统自动检查是否所有必要待办已完成，若是则推进内部流程\n\n" +
+            "【关联字典】\n" +
+            "- 涉及字段 todoType → 字典：order_todo_type（订单待办类型）")
     @PutMapping("/todo/{todoId}/complete")
     public Result<Void> completeTodo(HttpServletRequest request,
                                      @ApiParam("待办ID") @PathVariable Long todoId) {
@@ -47,7 +54,11 @@ public class AdminOrderTodoController {
         return Result.success();
     }
 
-    @ApiOperation("我的待办列表")
+    @ApiOperation(value = "我的待办列表", notes = "根据当前管理员ID和角色，查询分配给自己的未完成待办。\n" +
+            "超级管理员可看到所有待办，其他角色只能看到对应类型的待办\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 todoType → 字典：order_todo_type（订单待办类型）\n" +
+            "- 返回字段 orderStatus → 字典：order_status（订单状态）")
     @GetMapping("/todo/my-list")
     public Result<List<OrderTodoVO>> getMyTodos(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -56,7 +67,7 @@ public class AdminOrderTodoController {
         return Result.success(todos);
     }
 
-    @ApiOperation("我的待办数量")
+    @ApiOperation(value = "我的待办数量", notes = "返回当前管理员未完成的待办总数，用于首页角标/红点提醒")
     @GetMapping("/todo/my-count")
     public Result<Integer> getMyTodosCount(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -65,7 +76,7 @@ public class AdminOrderTodoController {
         return Result.success(count);
     }
 
-    @ApiOperation("定制师列表")
+    @ApiOperation(value = "定制师列表", notes = "获取所有定制师(CUSTOMIZER角色)的列表，用于更换定制师时选择目标定制师")
     @GetMapping("/todo/customizer-list")
     public Result<List<AdminBasicDTO>> getCustomizerList() {
         try {
@@ -79,7 +90,7 @@ public class AdminOrderTodoController {
         return Result.success(Collections.emptyList());
     }
 
-    @ApiOperation("更换定制师")
+    @ApiOperation(value = "更换定制师", notes = "将订单转派给另一位定制师。更换后原定制师的待办自动转移，订单时间线会记录此操作")
     @PutMapping("/{orderId}/customizer")
     public Result<Void> changeCustomizer(HttpServletRequest request,
                                          @ApiParam("订单ID") @PathVariable Long orderId,
@@ -90,7 +101,11 @@ public class AdminOrderTodoController {
         return Result.success();
     }
 
-    @ApiOperation("可签合同订单列表（保险已完成）")
+    @ApiOperation(value = "可签合同订单列表（保险已完成）", notes = "查询保险待办已完成、可以进入签合同环节的订单列表。\n" +
+            "用于合同管理页面展示待签合同的订单\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 todoType → 字典：order_todo_type（订单待办类型）\n" +
+            "- 返回字段 orderStatus → 字典：order_status（订单状态）")
     @GetMapping("/todo/contract-eligible")
     public Result<List<OrderTodoVO>> getContractEligibleOrders(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java
index fddef53..eb92d44 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java
@@ -31,7 +31,11 @@ public class AdminRefundController {
 
     // ==================== Refund Applications ====================
 
-    @ApiOperation("退款申请列表")
+    @ApiOperation(value = "退款申请列表", notes = "分页查询退款申请，支持按状态筛选。\n" +
+            "状态包括：PENDING(待审批)、APPROVED(已通过)、REJECTED(已拒绝)、REFUNDING(退款中)、REFUNDED(已退款)、CANCELLED(已撤回)、APPEAL(申诉中)\n\n" +
+            "【关联字典】\n" +
+            "- 筛选参数 status → 字典：refund_status（退款状态）\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @GetMapping("/list")
     public Result<PageResult<RefundApplicationVO>> listApplications(
             @ApiParam("状态") @RequestParam(required = false) String status,
@@ -40,14 +44,18 @@ public class AdminRefundController {
         return Result.success(refundApplicationService.listApplications(status, page, pageSize));
     }
 
-    @ApiOperation("退款申请详情")
+    @ApiOperation(value = "退款申请详情", notes = "返回退款申请的完整信息，包括退款原因、申请金额、实退金额、审批记录、申诉信息等\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @GetMapping("/{applicationId}")
     public Result<RefundApplicationVO> getDetail(@ApiParam("退款申请ID") @PathVariable Long applicationId) {
         return Result.success(refundApplicationService.getDetail(applicationId));
     }
 
     @ApiOperation(value = "审批退款申请", notes = "退款审批流程：查看退款申请 → 决定通过/拒绝 → 通过时填写实退金额 → 系统自动调起微信退款\n\n" +
-            "拒绝后用户可发起申诉")
+            "拒绝后用户可发起申诉\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @PutMapping("/{applicationId}/review")
     public Result<RefundApplicationVO> review(HttpServletRequest request,
                                                @ApiParam("退款申请ID") @PathVariable Long applicationId,
@@ -79,20 +87,26 @@ public class AdminRefundController {
 
     // ==================== Refund Reasons ====================
 
-    @ApiOperation("退款原因列表")
+    @ApiOperation(value = "退款原因列表", notes = "获取所有退款原因选项（含禁用的），用于退款原因管理页面\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 category → 字典：refund_reason_category（退款原因分类）")
     @GetMapping("/reason/list")
     public Result<List<RefundReasonVO>> listReasons() {
         return Result.success(refundReasonService.listReasons(false));
     }
 
-    @ApiOperation("创建退款原因")
+    @ApiOperation(value = "创建退款原因", notes = "新增退款原因选项，C端用户申请退款时可选择。按sortOrder排序展示\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 category → 字典：refund_reason_category（退款原因分类）")
     @PostMapping("/reason")
     public Result<RefundReasonVO> createReason(@ApiParam("创建退款原因请求") @Valid @RequestBody CreateRefundReasonRequest createRequest) {
         return Result.success(refundReasonService.createReason(
                 createRequest.getReasonText(), createRequest.getCategory(), createRequest.getSortOrder()));
     }
 
-    @ApiOperation("修改退款原因")
+    @ApiOperation(value = "修改退款原因", notes = "修改退款原因的文本、分类或排序，不影响已使用该原因的历史退款申请\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 category → 字典：refund_reason_category（退款原因分类）")
     @PutMapping("/reason/{reasonId}")
     public Result<RefundReasonVO> updateReason(@ApiParam("退款原因ID") @PathVariable Long reasonId,
                                                 @ApiParam("修改退款原因请求") @Valid @RequestBody UpdateRefundReasonRequest updateRequest) {
@@ -100,7 +114,7 @@ public class AdminRefundController {
                 reasonId, updateRequest.getReasonText(), updateRequest.getCategory(), updateRequest.getSortOrder()));
     }
 
-    @ApiOperation("删除退款原因")
+    @ApiOperation(value = "删除退款原因", notes = "软删除退款原因，删除后C端不再展示。不影响已使用该原因的历史退款申请")
     @DeleteMapping("/reason/{reasonId}")
     public Result<Void> deleteReason(@ApiParam("退款原因ID") @PathVariable Long reasonId) {
         refundReasonService.deleteReason(reasonId);

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java
index 9ff5005..e1bc0c8 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java
@@ -22,13 +22,17 @@ public class AdminRefundPolicyController {
 
     private final RefundPolicyService refundPolicyService;
 
-    @ApiOperation("退款政策列表")
+    @ApiOperation(value = "退款政策列表", notes = "【关联字典】\n" +
+            "- 返回字段 refundType → 字典：refund_type（退款类型）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/list")
     public Result<List<RefundPolicyVO>> list() {
         return Result.success(refundPolicyService.listPolicies());
     }
 
-    @ApiOperation("退款政策详情")
+    @ApiOperation(value = "退款政策详情", notes = "【关联字典】\n" +
+            "- 返回字段 refundType → 字典：refund_type（退款类型）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/{policyId}")
     public Result<RefundPolicyVO> detail(@ApiParam("退款政策ID") @PathVariable Long policyId) {
         return Result.success(refundPolicyService.getDetail(policyId));
@@ -36,7 +40,10 @@ public class AdminRefundPolicyController {
 
     @ApiOperation(value = "创建退款政策", notes = "退款政策定义按产品类型和距出发天数的退款比例阶梯\n\n" +
             "例如：出发前30天退90%，前15天退70%，前7天退50%，7天内不可退\n\n" +
-            "每种产品类型可配置独立的退款政策，用户申请退款时系统自动匹配")
+            "每种产品类型可配置独立的退款政策，用户申请退款时系统自动匹配\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 refundType → 字典：refund_type（退款类型）\n" +
+            "- 请求参数 productType → 字典：product_type（产品类型）")
     @PostMapping
     public Result<RefundPolicyVO> create(HttpServletRequest request,
                                           @ApiParam("创建退款政策请求") @Valid @RequestBody RefundPolicyRequest policyRequest) {
@@ -44,14 +51,17 @@ public class AdminRefundPolicyController {
         return Result.success(refundPolicyService.createPolicy(policyRequest, adminId));
     }
 
-    @ApiOperation("修改退款政策")
+    @ApiOperation(value = "修改退款政策", notes = "【关联字典】\n" +
+            "- 请求参数 refundType → 字典：refund_type（退款类型）\n" +
+            "- 请求参数 productType → 字典：product_type（产品类型）")
     @PutMapping("/{policyId}")
     public Result<RefundPolicyVO> update(@ApiParam("退款政策ID") @PathVariable Long policyId,
                                           @ApiParam("修改退款政策请求") @Valid @RequestBody RefundPolicyRequest policyRequest) {
         return Result.success(refundPolicyService.updatePolicy(policyId, policyRequest));
     }
 
-    @ApiOperation("删除退款政策")
+    @ApiOperation(value = "删除退款政策",
+            notes = "软删除退款政策。删除后该产品类型将使用默认退款规则。不影响已使用该政策处理的历史退款申请。")
     @DeleteMapping("/{policyId}")
     public Result<Void> delete(@ApiParam("退款政策ID") @PathVariable Long policyId) {
         refundPolicyService.deletePolicy(policyId);

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java
index 949f142..faf973b 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java
@@ -25,7 +25,15 @@ public class AdminWorkOrderController {
 
     private final WorkOrderService workOrderService;
 
-    @ApiOperation("工单列表")
+    @ApiOperation(value = "工单列表", notes = "分页查询工单，支持按状态/类型/优先级/订单编号/处理人筛选。\n" +
+            "工单用于处理旅行中的突发变更需求（如换房、换车、加景点等）\n\n" +
+            "【关联字典】\n" +
+            "- 筛选参数 status → 字典：work_order_status（工单状态）\n" +
+            "- 筛选参数 type → 字典：work_order_type（工单类型）\n" +
+            "- 筛选参数 priority → 字典：work_order_priority（工单优先级）\n" +
+            "- 返回字段 status → 字典：work_order_status（工单状态）\n" +
+            "- 返回字段 type → 字典：work_order_type（工单类型）\n" +
+            "- 返回字段 priority → 字典：work_order_priority（工单优先级）")
     @GetMapping("/list")
     public Result<PageResult<WorkOrderVO>> list(
             @ApiParam("状态: PENDING/PROCESSING/RESOLVED/REJECTED") @RequestParam(required = false) String status,
@@ -38,19 +46,32 @@ public class AdminWorkOrderController {
         return Result.success(workOrderService.listWorkOrders(status, type, priority, orderNo, assigneeAdminId, page, pageSize));
     }
 
-    @ApiOperation("工单详情")
+    @ApiOperation(value = "工单详情", notes = "返回工单完整信息，包括关联订单、资源详情、处理记录和备注列表\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：work_order_status（工单状态）\n" +
+            "- 返回字段 type → 字典：work_order_type（工单类型）\n" +
+            "- 返回字段 priority → 字典：work_order_priority（工单优先级）")
     @GetMapping("/{workOrderId}")
     public Result<WorkOrderVO> getDetail(@ApiParam("工单ID") @PathVariable Long workOrderId) {
         return Result.success(workOrderService.getDetail(workOrderId));
     }
 
-    @ApiOperation("工单统计(待处理数等)")
+    @ApiOperation(value = "工单统计", notes = "返回各状态的工单数量和紧急工单数，用于工单管理页面顶部统计卡片\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段中的状态key → 字典：work_order_status（工单状态）")
     @GetMapping("/stats")
     public Result<Map<String, Object>> getStats() {
         return Result.success(workOrderService.getStats());
     }
 
-    @ApiOperation("创建工单")
+    @ApiOperation(value = "创建工单", notes = "创建旅途中的变更工单，需关联订单ID。\n" +
+            "可指定处理人，未指定则进入待分配状态。可附带差价信息和资源详情JSON\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 type → 字典：work_order_type（工单类型）\n" +
+            "- 请求参数 priority → 字典：work_order_priority（工单优先级）\n" +
+            "- 返回字段 status → 字典：work_order_status（工单状态）\n" +
+            "- 返回字段 type → 字典：work_order_type（工单类型）\n" +
+            "- 返回字段 priority → 字典：work_order_priority（工单优先级）")
     @PostMapping
     public Result<WorkOrderVO> create(HttpServletRequest request,
                                        @Valid @RequestBody CreateWorkOrderRequest body) {
@@ -59,7 +80,10 @@ public class AdminWorkOrderController {
         return Result.success(workOrderService.createWorkOrder(adminId, adminName, body));
     }
 
-    @ApiOperation("处理工单(解决/驳回)")
+    @ApiOperation(value = "处理工单（解决/驳回）", notes = "解决时需填写处理结果(resolution)，驳回时需填写驳回原因(rejectReason)。\n" +
+            "可调整差价(costDifference)，正数表示加价，负数表示退费\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：work_order_status（工单状态）")
     @PutMapping("/{workOrderId}/process")
     public Result<WorkOrderVO> process(HttpServletRequest request,
                                         @ApiParam("工单ID") @PathVariable Long workOrderId,
@@ -69,7 +93,7 @@ public class AdminWorkOrderController {
         return Result.success(workOrderService.processWorkOrder(workOrderId, adminId, adminName, body));
     }
 
-    @ApiOperation("指派工单")
+    @ApiOperation(value = "指派工单", notes = "将工单分配给指定管理员处理。被指派人将在待办列表中看到该工单")
     @PutMapping("/{workOrderId}/assign")
     public Result<WorkOrderVO> assign(HttpServletRequest request,
                                        @ApiParam("工单ID") @PathVariable Long workOrderId,
@@ -80,7 +104,7 @@ public class AdminWorkOrderController {
         return Result.success(workOrderService.assignWorkOrder(workOrderId, adminId, adminName, assigneeId, assigneeName));
     }
 
-    @ApiOperation("添加备注")
+    @ApiOperation(value = "添加工单备注", notes = "在工单中追加备注信息，用于内部沟通和处理过程记录")
     @PostMapping("/{workOrderId}/comment")
     public Result<WorkOrderVO> addComment(HttpServletRequest request,
                                            @ApiParam("工单ID") @PathVariable Long workOrderId,
@@ -94,7 +118,7 @@ public class AdminWorkOrderController {
         return Result.success(workOrderService.addComment(workOrderId, adminId, adminName, content));
     }
 
-    @ApiOperation("按订单查工单数量")
+    @ApiOperation(value = "按订单查工单数量", notes = "返回指定订单关联的工单总数，用于订单详情页展示工单角标")
     @GetMapping("/count-by-order/{orderId}")
     public Result<Integer> countByOrder(@ApiParam("订单ID") @PathVariable Long orderId) {
         return Result.success(workOrderService.countByOrderId(orderId));

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java
index 0d65e46..e8684ef 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java
@@ -16,7 +16,7 @@ import java.util.List;
 /**
  * 相册内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  */
-@Api(tags = "【内部接口】小程序相册（Feign调用）")
+@Api(tags = "【内部接口】小程序相册（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/album")
 @RequiredArgsConstructor
@@ -24,13 +24,14 @@ public class InternalAlbumController {
 
     private final AlbumService albumService;
 
-    @ApiOperation("用户有相册的订单列表")
+    @ApiOperation(value = "用户有相册的订单列表", notes = "返回用户所有有相册文件夹的订单（含订单基本信息和相册封面），用于C端'我的相册'入口")
     @GetMapping("/orders")
     public Result<List<AlbumOrderVO>> listAlbumOrders(@RequestParam Long userId) {
         return Result.success(albumService.listUserAlbumOrders(userId));
     }
 
-    @ApiOperation("订单的文件夹列表")
+    @ApiOperation(value = "订单的文件夹列表",
+            notes = "内部服务间调用。返回指定用户指定订单下的相册文件夹列表，会校验订单归属权限。")
     @GetMapping("/order/{orderId}/folders")
     public Result<List<AlbumFolderVO>> listFolders(
             @RequestParam Long userId,
@@ -38,7 +39,10 @@ public class InternalAlbumController {
         return Result.success(albumService.listUserFolders(userId, orderId));
     }
 
-    @ApiOperation("文件夹下的文件列表")
+    @ApiOperation(value = "文件夹下的文件列表", notes = "**关联字典**：\n" +
+            "- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频\n" +
+            "- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点\n" +
+            "- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆")
     @GetMapping("/folder/{folderId}/files")
     public Result<PageResult<AlbumFileVO>> listFiles(
             @RequestParam Long userId,
@@ -48,7 +52,7 @@ public class InternalAlbumController {
         return Result.success(albumService.listUserFiles(userId, folderId, page, size));
     }
 
-    @ApiOperation("获取文件下载链接")
+    @ApiOperation(value = "获取文件下载链接", notes = "生成带签名的临时下载URL（有效期1小时），用于C端用户下载原图/视频")
     @GetMapping("/file/{albumFileId}/download-url")
     public Result<String> getDownloadUrl(
             @RequestParam Long userId,

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java
index 0fd0c6a..110daf9 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java
@@ -11,7 +11,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "【内部接口】工作台统计（Feign调用）")
+@Api(tags = "【内部接口】工作台统计（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/order/dashboard")
 @RequiredArgsConstructor
@@ -19,7 +19,9 @@ public class InternalDashboardController {
 
     private final DashboardStatsService dashboardStatsService;
 
-    @ApiOperation("概览统计（支持定制师/全局，支持今日/本周/本月）")
+    @ApiOperation(value = "概览统计", notes = "返回订单量、成交金额、待处理订单数等概览数据。\n" +
+            "传customizerId则返回该定制师的数据，不传则返回全局数据。\n" +
+            "period支持: today(今日)、week(本周)、month(本月)")
     @GetMapping("/overview-stats")
     public Result<Map<String, Object>> getOverviewStats(
             @ApiParam("定制师ID，不传则为全局") @RequestParam(required = false) Long customizerId,
@@ -27,7 +29,9 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getOverviewStats(customizerId, period));
     }
 
-    @ApiOperation("待办分类汇总")
+    @ApiOperation(value = "待办分类汇总", notes = "按待办类型分组统计当前管理员的未完成待办数量，用于工作台待办卡片展示\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段中的待办类型key → 字典：order_todo_type（订单待办类型）")
     @GetMapping("/todo-summary")
     public Result<Map<String, Object>> getTodoSummary(
             @ApiParam("管理员ID") @RequestParam Long adminId,
@@ -35,7 +39,7 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getTodoSummary(adminId, roleKey));
     }
 
-    @ApiOperation("数据趋势（按天聚合）")
+    @ApiOperation(value = "数据趋势", notes = "按天聚合的订单量和金额趋势数据，用于折线图展示。支持最近7天或30天")
     @GetMapping("/trend")
     public Result<List<Map<String, Object>>> getTrend(
             @ApiParam("定制师ID，不传则为全局") @RequestParam(required = false) Long customizerId,
@@ -46,7 +50,9 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getTrend(customizerId, days));
     }
 
-    @ApiOperation("转化漏斗")
+    @ApiOperation(value = "转化漏斗", notes = "展示订单从创建→支付→确认→完成的转化率漏斗数据\n\n" +
+            "【关联字典】\n" +
+            "- 涉及字段 订单状态 → 字典：order_status（订单状态）")
     @GetMapping("/funnel")
     public Result<Map<String, Object>> getFunnel(
             @ApiParam("定制师ID，不传则为全局") @RequestParam(required = false) Long customizerId,
@@ -54,7 +60,10 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getFunnel(customizerId, period));
     }
 
-    @ApiOperation("即将出行列表")
+    @ApiOperation(value = "即将出行列表", notes = "返回最近即将出发的订单列表，按出发日期升序。用于工作台提醒关注即将出行的客户\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/upcoming-trips")
     public Result<List<Map<String, Object>>> getUpcomingTrips(
             @ApiParam("定制师ID，不传则为全局") @RequestParam(required = false) Long customizerId,
@@ -62,14 +71,14 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getUpcomingTrips(customizerId, limit));
     }
 
-    @ApiOperation("业绩排行（本月定制师排名）")
+    @ApiOperation(value = "业绩排行", notes = "按定制师维度统计成交金额排名，支持本周/本月周期。用于工作台排行榜展示")
     @GetMapping("/ranking")
     public Result<List<Map<String, Object>>> getRanking(
             @ApiParam("时间范围: month/week") @RequestParam(defaultValue = "month") String period) {
         return Result.success(dashboardStatsService.getRanking(period));
     }
 
-    @ApiOperation("日历事件")
+    @ApiOperation(value = "日历事件", notes = "返回指定月份的出发日期事件列表，用于工作台日历组件展示。每个事件包含订单基本信息")
     @GetMapping("/calendar-events")
     public Result<List<Map<String, Object>>> getCalendarEvents(
             @ApiParam("定制师ID") @RequestParam(required = false) Long customizerId,
@@ -78,14 +87,14 @@ public class InternalDashboardController {
         return Result.success(dashboardStatsService.getCalendarEvents(customizerId, year, month));
     }
 
-    @ApiOperation("财务统计")
+    @ApiOperation(value = "财务统计", notes = "返回收入、成本、利润等财务汇总数据，支持按时间周期统计")
     @GetMapping("/finance-stats")
     public Result<Map<String, Object>> getFinanceStats(
             @ApiParam("时间范围") @RequestParam(defaultValue = "today") String period) {
         return Result.success(dashboardStatsService.getFinanceStats(period));
     }
 
-    @ApiOperation("退款汇总")
+    @ApiOperation(value = "退款汇总", notes = "返回退款总额、退款笔数、退款率等汇总信息。传customizerId可查看单个定制师的退款数据")
     @GetMapping("/refund-summary")
     public Result<Map<String, Object>> getRefundSummary(
             @ApiParam("定制师ID") @RequestParam(required = false) Long customizerId) {

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java
index bb7a01e..cd52e45 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java
@@ -12,7 +12,7 @@ import org.springframework.web.bind.annotation.*;
 
 import java.util.Map;
 
-@Api(tags = "【内部接口】定制师订单（Feign调用）")
+@Api(tags = "【内部接口】定制师订单（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/order")
 @RequiredArgsConstructor
@@ -20,20 +20,29 @@ public class InternalDesignerOrderController {
 
     private final OrderService orderService;
 
-    @ApiOperation("获取定制师订单统计")
+    @ApiOperation(value = "获取定制师订单统计", notes = "返回指定定制师的订单统计数据（各状态数量、总金额等），用于定制师工作台概览\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段中的状态key → 字典：order_status（订单状态）")
     @GetMapping("/designer-stats")
     public Result<Map<String, Object>> getDesignerOrderStats(
             @ApiParam("定制师管理员ID") @RequestParam Long customizerId) {
         return Result.success(orderService.getDesignerOrderStats(customizerId));
     }
 
-    @ApiOperation("获取全局订单统计")
+    @ApiOperation(value = "获取全局订单统计", notes = "返回全平台的订单统计数据（各状态数量、总金额等），用于管理层工作台概览\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段中的状态key → 字典：order_status（订单状态）")
     @GetMapping("/global-stats")
     public Result<Map<String, Object>> getGlobalOrderStats() {
         return Result.success(orderService.getGlobalOrderStats());
     }
 
-    @ApiOperation("定制师订单列表")
+    @ApiOperation(value = "定制师订单列表", notes = "分页查询指定定制师负责的订单，支持按状态和关键词筛选\n\n" +
+            "【关联字典】\n" +
+            "- 筛选参数 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/designer-list")
     public Result<PageResult<OrderListVO>> listDesignerOrders(
             @ApiParam("定制师管理员ID") @RequestParam Long customizerId,

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java
index 97b3871..b1bf9e7 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java
@@ -15,7 +15,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.math.BigDecimal;
 import java.util.List;
 
-@Api(tags = "【内部接口】早鸟优惠（Feign调用）")
+@Api(tags = "【内部接口】早鸟优惠（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/early-bird")
 @RequiredArgsConstructor
@@ -23,14 +23,17 @@ public class InternalEarlyBirdController {
 
     private final EarlyBirdPlanService earlyBirdPlanService;
 
-    @ApiOperation("获取当前有效的早鸟优惠计划列表")
+    @ApiOperation(value = "获取当前有效的早鸟优惠计划列表", notes = "返回当前日期处于生效期内且已启用的早鸟计划，C端下单时展示可用优惠")
     @GetMapping("/active")
     public Result<List<EarlyBirdPlanVO>> listActivePlans() {
         List<EarlyBirdPlanVO> plans = earlyBirdPlanService.listActivePlans();
         return Result.success(plans);
     }
 
-    @ApiOperation("匹配最优早鸟优惠计划")
+    @ApiOperation(value = "匹配最优早鸟优惠计划", notes = "根据产品类型、出行人数、订单总价匹配优惠金额最大的早鸟计划。\n" +
+            "无匹配返回null。供下单时自动匹配调用\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 productType → 字典：product_type（产品类型）")
     @GetMapping("/match")
     public Result<EarlyBirdPlanVO> matchPlan(
             @RequestParam String productType,

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java
index e84a0e6..310b627 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java
@@ -15,7 +15,7 @@ import javax.validation.Valid;
  * C端发票内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "【内部接口】小程序发票（Feign调用）")
+@Api(tags = "【内部接口】小程序发票（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/invoice")
 @RequiredArgsConstructor
@@ -23,21 +23,33 @@ public class InternalInvoiceController {
 
     private final InvoiceService invoiceService;
 
-    @ApiOperation("申请开票")
+    @ApiOperation(value = "申请开票", notes = "用户对已支付订单申请开具电子发票。支持个人和企业抬头。\n" +
+            "同一订单只能开一次发票（可换开）\n\n" +
+            "**关联字典**：\n" +
+            "- invoice_title_type（抬头类型，请求/返回字段titleType）：PERSONAL=个人, COMPANY=企业\n" +
+            "- invoice_type（发票类型，返回字段invoiceType）：NORMAL=普通发票, SPECIAL=专用发票\n" +
+            "- invoice_status（发票状态，返回字段status）：PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废")
     @PostMapping("/apply")
     public Result<InvoiceVO> applyInvoice(@RequestParam Long userId,
                                           @Valid @RequestBody InvoiceApplyRequest request) {
         return Result.success(invoiceService.applyInvoice(userId, request));
     }
 
-    @ApiOperation("发票详情")
+    @ApiOperation(value = "发票详情", notes = "**关联字典**：\n" +
+            "- invoice_title_type（抬头类型，返回字段titleType）：PERSONAL=个人, COMPANY=企业\n" +
+            "- invoice_type（发票类型，返回字段invoiceType）：NORMAL=普通发票, SPECIAL=专用发票\n" +
+            "- invoice_status（发票状态，返回字段status）：PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废")
     @GetMapping("/{id}")
     public Result<InvoiceVO> getInvoiceDetail(@RequestParam Long userId,
                                               @PathVariable Long id) {
         return Result.success(invoiceService.getInvoiceDetail(userId, id));
     }
 
-    @ApiOperation("通过订单ID查询发票")
+    @ApiOperation(value = "通过订单ID查询发票", notes = "查询订单关联的发票信息。未开票时返回null\n\n" +
+            "**关联字典**：\n" +
+            "- invoice_title_type（抬头类型，返回字段titleType）：PERSONAL=个人, COMPANY=企业\n" +
+            "- invoice_type（发票类型，返回字段invoiceType）：NORMAL=普通发票, SPECIAL=专用发票\n" +
+            "- invoice_status（发票状态，返回字段status）：PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废")
     @GetMapping("/order/{orderId}")
     public Result<InvoiceVO> getInvoiceByOrderId(@RequestParam Long userId,
                                                   @PathVariable Long orderId) {

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java
index c27da3a..ec5f305 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java
@@ -24,7 +24,7 @@ import java.util.Map;
  * C端订单内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "【内部接口】小程序订单（Feign调用）")
+@Api(tags = "【内部接口】小程序订单（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/order")
 @RequiredArgsConstructor
@@ -32,7 +32,13 @@ public class InternalMpOrderController {
 
     private final OrderService orderService;
 
-    @ApiOperation("创建订单")
+    @ApiOperation(value = "创建订单", notes = "供BFF层调用的C端下单接口。创建后返回订单详情（含支付信息），前端可直接跳转支付\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 请求参数 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @PostMapping("/create")
     public Result<OrderDetailVO> createOrder(@RequestParam Long userId,
                                              @Valid @RequestBody CreateOrderRequest request) {
@@ -41,21 +47,32 @@ public class InternalMpOrderController {
         return Result.success(detail);
     }
 
-    @ApiOperation("订单列表")
+    @ApiOperation(value = "订单列表", notes = "【关联字典】\n" +
+            "- 筛选参数 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/list")
     public Result<PageResult<MpOrderListVO>> listOrders(@RequestParam Long userId,
                                                         MpOrderQueryRequest query) {
         return Result.success(orderService.listUserOrders(userId, query));
     }
 
-    @ApiOperation("订单详情")
+    @ApiOperation(value = "订单详情", notes = "【关联字典】\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）\n" +
+            "- 返回字段 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 返回字段 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 返回字段 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 timeline[].action → 字典：order_timeline_action（订单操作类型）")
     @GetMapping("/{orderId}")
     public Result<OrderDetailVO> getOrder(@RequestParam Long userId,
                                           @PathVariable Long orderId) {
         return Result.success(orderService.getUserOrderDetail(userId, orderId));
     }
 
-    @ApiOperation("取消订单")
+    @ApiOperation(value = "取消订单",
+            notes = "内部服务间调用，供BFF层调用的用户取消订单接口。仅允许取消待支付/已付定金状态的订单。")
     @PostMapping("/{orderId}/cancel")
     public Result<Void> cancelOrder(@RequestParam Long userId,
                                     @PathVariable Long orderId,
@@ -65,7 +82,8 @@ public class InternalMpOrderController {
         return Result.success();
     }
 
-    @ApiOperation("订单资源详情（按分类）")
+    @ApiOperation(value = "订单资源详情（按分类）",
+            notes = "内部服务间调用。解析订单的产品快照JSON，按资源类型分类提取资源详情（景区/酒店/活动/餐厅等），返回Map结构。")
     @GetMapping("/{orderId}/resources")
     public Result<Map<String, List<Map<String, Object>>>> getOrderResources(
             @RequestParam Long userId,
@@ -73,7 +91,7 @@ public class InternalMpOrderController {
         return Result.success(orderService.getOrderSnapshotResources(userId, orderId));
     }
 
-    @ApiOperation("通过联系人手机号+姓名查找订单（无需登录）")
+    @ApiOperation(value = "通过联系人手机号+姓名查找订单", notes = "无需登录。用于管理员代下单场景：管理员创建订单后用户通过手机号+姓名查找并绑定订单")
     @GetMapping("/lookup")
     public Result<java.util.List<MpOrderListVO>> lookupByContact(
             @RequestParam String contactPhone,
@@ -81,7 +99,8 @@ public class InternalMpOrderController {
         return Result.success(orderService.lookupByContact(contactPhone, contactName));
     }
 
-    @ApiOperation("绑定未绑定的订单（通过联系人手机号+姓名）")
+    @ApiOperation(value = "绑定未绑定的订单", notes = "将userId=NULL且联系人手机号+姓名匹配的订单绑定到当前用户。\n" +
+            "用于管理员代下单后用户登录自动关联订单。返回绑定的订单数量")
     @PostMapping("/bind-by-contact")
     public Result<Integer> bindByContact(@RequestParam Long userId,
                                          @Valid @RequestBody BindByContactRequest request) {
@@ -89,7 +108,7 @@ public class InternalMpOrderController {
         return Result.success(bindCount);
     }
 
-    @ApiOperation("客户同意解锁订单")
+    @ApiOperation(value = "客户同意解锁订单", notes = "管理员申请修改锁定订单后，C端用户确认同意解锁。解锁后管理员可重新编辑订单")
     @PostMapping("/{orderId}/approve-unlock")
     public Result<Void> approveUnlock(@RequestParam Long userId,
                                        @PathVariable Long orderId) {
@@ -103,13 +122,16 @@ public class InternalMpOrderController {
         return Result.success(orderService.getUpcomingDepartures(userId));
     }
 
-    @ApiOperation("各状态订单数量")
+    @ApiOperation(value = "各状态订单数量", notes = "返回用户各状态的订单数量Map，用于小程序订单页Tab角标显示\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段中的状态key → 字典：order_status（订单状态）")
     @GetMapping("/count")
     public Result<Map<String, Integer>> countByStatus(@RequestParam Long userId) {
         return Result.success(orderService.countByStatusForUser(userId));
     }
 
-    @ApiOperation("标记订单已评价（评价服务回调）")
+    @ApiOperation(value = "标记订单已评价", notes = "评价服务(review-service)在用户发布评价后回调此接口，将订单标记为已评价。\n" +
+            "标记后订单详情不再显示'去评价'按钮")
     @PutMapping("/{orderId}/mark-reviewed")
     public Result<Void> markReviewed(@PathVariable Long orderId) {
         orderService.markReviewed(orderId);
@@ -118,7 +140,13 @@ public class InternalMpOrderController {
 
     @ApiOperation(value = "用户修改订单", notes = "用户可修改出发日期和出行人，修改后重走内部流程（级联检测+价格重算）。" +
             "仅待支付/已付定金/已支付/已确认/待付尾款/待出发状态可修改。" +
-            "内部流程已启动的订单修改后会通知定制师，返回message中包含提示")
+            "内部流程已启动的订单修改后会通知定制师，返回message中包含提示\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 请求参数 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @PutMapping("/{orderId}/edit")
     public Result<OrderDetailVO> userEditOrder(@RequestParam Long userId,
                                                 @PathVariable Long orderId,

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java
index db0d1cc..8e4b990 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java
@@ -10,7 +10,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "【内部接口】小程序行程（Feign调用）")
+@Api(tags = "【内部接口】小程序行程（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/trip")
 @RequiredArgsConstructor
@@ -18,20 +18,29 @@ public class InternalMpTripController {
 
     private final TripService tripService;
 
-    @ApiOperation("行程列表")
+    @ApiOperation(value = "行程列表", notes = "返回用户所有有效订单的行程概要列表（已确认/待出发/出行中/已完成），按出发日期排序\n\n" +
+            "**关联字典**：\n" +
+            "- order_status（订单状态，返回字段status）：CONFIRMED=已确认, PENDING_DEPARTURE=待出发, TRAVELLING=出行中, COMPLETED=已完成\n" +
+            "- trip_phase（行程阶段，返回字段tripPhase）：BEFORE_START=出发前, IN_PROGRESS=出行中, ENDED=已结束")
     @GetMapping("/list")
     public Result<List<Map<String, Object>>> getTripList(@RequestParam Long userId) {
         return Result.success(tripService.getTripList(userId));
     }
 
-    @ApiOperation("行程详情")
+    @ApiOperation(value = "行程详情", notes = "返回订单的完整行程信息，包括每日行程节点、酒店安排、车辆安排、天气预报等\n\n" +
+            "**关联字典**：\n" +
+            "- order_status（订单状态，返回字段status）：CONFIRMED=已确认, PENDING_DEPARTURE=待出发, TRAVELLING=出行中, COMPLETED=已完成\n" +
+            "- trip_phase（行程阶段，返回字段tripPhase）：BEFORE_START=出发前, IN_PROGRESS=出行中, ENDED=已结束")
     @GetMapping("/{orderId}")
     public Result<Map<String, Object>> getTripDetail(@RequestParam Long userId,
                                                       @PathVariable Long orderId) {
         return Result.success(tripService.getTripDetail(userId, orderId));
     }
 
-    @ApiOperation("今日行程")
+    @ApiOperation(value = "今日行程", notes = "返回用户今天的行程安排。如果今天有正在出行的订单，返回当天的行程节点和安排；否则返回null\n\n" +
+            "**关联字典**：\n" +
+            "- order_status（订单状态，返回字段status）：CONFIRMED=已确认, PENDING_DEPARTURE=待出发, TRAVELLING=出行中, COMPLETED=已完成\n" +
+            "- trip_phase（行程阶段，返回字段tripPhase）：BEFORE_START=出发前, IN_PROGRESS=出行中, ENDED=已结束")
     @GetMapping("/today")
     public Result<Map<String, Object>> getTodayTrip(@RequestParam Long userId) {
         Map<String, Object> trip = tripService.getTodayTrip(userId);

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java
index 887cf27..38d3022 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java
@@ -12,7 +12,7 @@ import org.springframework.web.bind.annotation.*;
 
 import javax.validation.Valid;
 
-@Api(tags = "内部-订单统计")
+@Api(tags = "内部-订单统计", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/order")
 @RequiredArgsConstructor
@@ -21,19 +21,24 @@ public class InternalOrderStatsController {
     private final OrderService orderService;
     private final InvoiceService invoiceService;
 
-    @ApiOperation("获取产品已购出行人总数")
+    @ApiOperation(value = "获取产品已购出行人总数", notes = "统计指定产品的有效订单（非取消/非退款）出行人总数，用于产品详情页显示'已报名X人'")
     @GetMapping("/product-sold-count")
     public Result<Integer> getProductSoldCount(@RequestParam Long productId) {
         return Result.success(orderService.getProductSoldCount(productId));
     }
 
-    @ApiOperation("获取产品参与家庭数")
+    @ApiOperation(value = "获取产品参与家庭数", notes = "统计指定产品的有效订单数（一个订单视为一个家庭），用于产品详情页显示'已有X个家庭参与'")
     @GetMapping("/participant-family-count")
     public Result<Integer> getParticipantFamilyCount(@RequestParam Long productId) {
         return Result.success(orderService.getParticipantFamilyCount(productId));
     }
 
-    @ApiOperation("发票换开")
+    @ApiOperation(value = "发票换开", notes = "已开发票更换抬头信息（如个人改企业、更换公司名称等）。\n" +
+            "原发票作废，重新生成新发票\n\n" +
+            "**关联字典**：\n" +
+            "- invoice_title_type（抬头类型，请求/返回字段titleType）：PERSONAL=个人, COMPANY=企业\n" +
+            "- invoice_type（发票类型，返回字段invoiceType）：NORMAL=普通发票, SPECIAL=专用发票\n" +
+            "- invoice_status（发票状态，返回字段status）：PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废")
     @PostMapping("/invoice/reissue")
     public Result<InvoiceVO> reissueInvoice(@RequestBody @Valid InvoiceReissueRequest request) {
         return Result.success(invoiceService.reissueInvoice(request));

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java
index 2b39654..656382a 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java
@@ -11,7 +11,7 @@ import org.springframework.web.bind.annotation.*;
 /**
  * Internal API for payment service - 出行人验证
  */
-@Api(tags = "【内部接口】订单出行人（Feign调用）")
+@Api(tags = "【内部接口】订单出行人（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/order/traveler")
 @RequiredArgsConstructor
@@ -19,7 +19,11 @@ public class InternalOrderTravelerController {
 
     private final OrderTravelerService orderTravelerService;
 
-    @ApiOperation("验证订单出行人信息（供支付服务调用）")
+    @ApiOperation(value = "验证订单出行人信息", notes = "供支付服务在发起支付前调用。验证出行人数量是否满足订单要求、证件信息是否完整。\n" +
+            "返回验证结果，包含是否通过和具体错误信息列表\n\n" +
+            "【关联字典】\n" +
+            "- 涉及字段 出行人证件类型 → 字典：id_card_type（证件类型）\n" +
+            "- 涉及字段 出行人类型 → 字典：traveler_type（出行人类型）")
     @GetMapping("/validate/{orderId}")
     public Result<TravelerValidationDTO> validateTravelers(@PathVariable Long orderId) {
         TravelerValidationDTO validation = orderTravelerService.validateTravelers(orderId);

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java
index b708e85..be4a57c 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java
@@ -21,7 +21,7 @@ import java.util.stream.Collectors;
  * Internal endpoints for payment-service to call via Feign.
  * Not exposed through gateway, no authentication interceptor.
  */
-@Api(tags = "【内部接口】订单-支付/合同/保险（Feign调用）")
+@Api(tags = "【内部接口】订单-支付/合同/保险（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/order")
 @RequiredArgsConstructor
@@ -30,13 +30,16 @@ public class InternalPaymentOrderController {
     private final OrderService orderService;
     private final OrderTodoService orderTodoService;
 
-    @ApiOperation("获取订单支付信息")
+    @ApiOperation(value = "获取订单支付信息", notes = "供支付服务调用。返回订单号、应付金额、定金金额、已付金额等支付所需信息")
     @GetMapping("/{orderId}/pay-info")
     public Result<OrderPayInfoDTO> getPayInfo(@PathVariable Long orderId) {
         return Result.success(orderService.getPayInfo(orderId));
     }
 
-    @ApiOperation("通知支付成功")
+    @ApiOperation(value = "通知支付成功", notes = "支付服务收到微信支付回调后调用。更新订单状态(PENDING_PAY→DEPOSIT_PAID/PAID)和已付金额。\n" +
+            "幂等处理：重复调用不会重复更新\n\n" +
+            "【关联字典】\n" +
+            "- 涉及字段 订单status → 字典：order_status（订单状态）")
     @PostMapping("/payment-result")
     public Result<Void> notifyPaymentResult(@RequestBody PaymentResultDTO dto) {
         orderService.handlePaymentSuccess(dto.getOrderId(), dto.getPayType(),
@@ -44,14 +47,16 @@ public class InternalPaymentOrderController {
         return Result.success();
     }
 
-    @ApiOperation("通知退款成功")
+    @ApiOperation(value = "通知退款成功", notes = "支付服务收到微信退款回调后调用。更新订单已退金额，若全额退款则将订单状态改为已退款(REFUNDED)")
     @PostMapping("/refund-result")
     public Result<Void> notifyRefundResult(@RequestBody RefundResultDTO dto) {
         orderService.handleRefundSuccess(dto.getOrderId(), dto.getRefundAmount());
         return Result.success();
     }
 
-    @ApiOperation("获取订单基本信息(供合同服务调用)")
+    @ApiOperation(value = "获取订单基本信息(供合同服务调用)", notes = "【关联字典】\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/{orderId}/basic")
     public Result<Map<String, Object>> getOrderBasic(@PathVariable Long orderId) {
         OrderInfo order = orderService.getById(orderId);
@@ -80,7 +85,8 @@ public class InternalPaymentOrderController {
         return Result.success(data);
     }
 
-    @ApiOperation("获取用户订单ID列表(供合同服务调用)")
+    @ApiOperation(value = "获取用户订单ID列表(供合同服务调用)",
+            notes = "内部服务间调用。返回指定用户的所有订单ID列表，供合同服务查询用户关联合同时使用。")
     @GetMapping("/ids-by-user")
     public Result<List<Long>> getOrderIdsByUser(@RequestParam Long userId) {
         List<OrderInfo> orders = orderService.list(
@@ -94,7 +100,8 @@ public class InternalPaymentOrderController {
         return Result.success(ids);
     }
 
-    @ApiOperation("完成待办项(供合同/保险服务调用)")
+    @ApiOperation(value = "完成待办项(供合同/保险服务调用)",
+            notes = "内部服务间调用。合同服务签约完成或保险服务投保完成后调用此接口，将对应待办标记为已完成。系统自动检查是否所有必要待办已完成并推进内部流程。")
     @PostMapping("/{orderId}/complete-todo/{todoType}")
     public Result<Void> completeTodoByType(@PathVariable Long orderId,
                                             @PathVariable String todoType) {

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java
index 2464f08..f7c334f 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java
@@ -17,7 +17,7 @@ import org.springframework.web.bind.annotation.*;
 import javax.validation.Valid;
 import java.util.List;
 
-@Api(tags = "【内部接口】退款（Feign调用）")
+@Api(tags = "【内部接口】退款（Feign调用）", hidden = true)
 @RestController
 @RequiredArgsConstructor
 public class InternalRefundController {
@@ -27,20 +27,26 @@ public class InternalRefundController {
 
     // ==================== C-end (BFF → order-service) ====================
 
-    @ApiOperation(value = "退款金额预览", notes = "退款预览：根据退款政策和距出发天数，计算可退金额和退款比例")
+    @ApiOperation(value = "退款金额预览", notes = "退款预览：根据退款政策和距出发天数，计算可退金额和退款比例\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 refundType → 字典：refund_type（退款类型）")
     @GetMapping("/internal/mp/order/{orderId}/refund-preview")
     public Result<RefundPreviewVO> preview(@RequestParam("userId") Long userId,
                                             @PathVariable Long orderId) {
         return Result.success(refundApplicationService.previewRefund(orderId, userId));
     }
 
-    @ApiOperation("退款原因列表")
+    @ApiOperation(value = "退款原因列表（C端）", notes = "返回启用中的退款原因选项，供C端用户申请退款时选择\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 category → 字典：refund_reason_category（退款原因分类）")
     @GetMapping("/internal/mp/order/refund-reasons")
     public Result<List<RefundReasonVO>> listReasons() {
         return Result.success(refundReasonService.listReasons(true));
     }
 
-    @ApiOperation(value = "提交退款申请", notes = "退款申请流程：用户选择退款原因 → 填写退款说明 → 系统根据退款政策计算可退金额 → 生成退款申请(PENDING状态) → 等待管理员审批")
+    @ApiOperation(value = "提交退款申请", notes = "退款申请流程：用户选择退款原因 → 填写退款说明 → 系统根据退款政策计算可退金额 → 生成退款申请(PENDING状态) → 等待管理员审批\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @PostMapping("/internal/mp/order/{orderId}/refund")
     public Result<RefundApplicationVO> apply(@RequestParam("userId") Long userId,
                                               @RequestParam(value = "userName", required = false) String userName,
@@ -49,14 +55,18 @@ public class InternalRefundController {
         return Result.success(refundApplicationService.apply(orderId, userId, userName, request));
     }
 
-    @ApiOperation("退款申请详情")
+    @ApiOperation(value = "退款申请详情（C端）", notes = "返回退款申请信息，仅允许查看自己的退款申请\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @GetMapping("/internal/mp/order/refund/{applicationId}")
     public Result<RefundApplicationVO> getDetail(@RequestParam("userId") Long userId,
                                                    @PathVariable Long applicationId) {
         return Result.success(refundApplicationService.getDetailForUser(applicationId, userId));
     }
 
-    @ApiOperation("根据订单ID获取最新退款申请详情")
+    @ApiOperation(value = "根据订单ID获取最新退款申请", notes = "返回订单关联的最新一条退款申请，用于订单详情页展示退款进度。无退款申请时返回null\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：refund_status（退款状态）")
     @GetMapping("/internal/mp/order/{orderId}/refund-detail")
     public Result<RefundApplicationVO> getDetailByOrder(@RequestParam("userId") Long userId,
                                                           @PathVariable Long orderId) {
@@ -72,7 +82,7 @@ public class InternalRefundController {
         return Result.success(refundApplicationService.appeal(applicationId, userId, request));
     }
 
-    @ApiOperation("撤回退款申请")
+    @ApiOperation(value = "撤回退款申请", notes = "用户主动撤回退款申请。仅在待审批(PENDING)状态下可撤回。撤回后订单恢复原状态")
     @PostMapping("/internal/mp/order/refund/{applicationId}/cancel")
     public Result<Void> cancel(@RequestParam("userId") Long userId,
                                 @PathVariable Long applicationId) {
@@ -82,16 +92,18 @@ public class InternalRefundController {
 
     // ==================== Approval callback ====================
 
-    @ApiOperation("企微退款申诉审批结果回调")
+    @ApiOperation(value = "企微退款申诉审批结果回调", notes = "企微OA审批完成后由callback-service调用。\n" +
+            "审批通过则退款申请状态变为APPEAL_APPROVED，等待管理员确认实退金额后执行退款")
     @PostMapping("/internal/order/refund-appeal-result")
-    public Result<?> handleRefundAppealResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleRefundAppealResult(@RequestBody ApprovalResultDTO dto) {
         refundApplicationService.handleAppealResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();
     }
 
-    @ApiOperation("企微退款申请审批结果回调")
+    @ApiOperation(value = "企微退款申请审批结果回调", notes = "企微OA审批完成后由callback-service调用。\n" +
+            "审批通过则自动执行微信退款，审批拒绝则退款申请状态变为REJECTED")
     @PostMapping("/internal/order/refund-application-result")
-    public Result<?> handleRefundApplicationResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleRefundApplicationResult(@RequestBody ApprovalResultDTO dto) {
         refundApplicationService.handleApplicationApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();
     }

`hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java
index f29e8f9..9b3806e 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java
@@ -35,7 +35,13 @@ public class MpOrderController {
     private static final String ORDER_CREATE_DEDUP = "order:create:dedup:";
 
     @ApiOperation(value = "创建订单", notes = "C端下单流程：选择产品 → 填写联系人信息和出行人 → 系统报价 → 生成订单(PENDING_PAY状态)\n\n" +
-            "联系人和出行人是独立概念，联系人不必是出行人之一")
+            "联系人和出行人是独立概念，联系人不必是出行人之一\n\n" +
+            "【关联字典】\n" +
+            "- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 请求参数 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @PostMapping("/create")
     public Result<OrderInfo> createOrder(HttpServletRequest request,
                                            @ApiParam("创建订单请求") @Valid @RequestBody CreateOrderRequest createRequest) {
@@ -55,7 +61,12 @@ public class MpOrderController {
         }
     }
 
-    @ApiOperation("我的订单列表")
+    @ApiOperation(value = "我的订单列表", notes = "查询当前用户的订单列表，支持按状态筛选。\n" +
+            "用户需先完善个人资料(realName)后才能看到订单\n\n" +
+            "【关联字典】\n" +
+            "- 筛选参数 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）")
     @GetMapping("/list")
     public Result<PageResult<MpOrderListVO>> listOrders(HttpServletRequest request,
                                                            @ApiParam("订单查询请求") MpOrderQueryRequest queryRequest) {
@@ -64,7 +75,15 @@ public class MpOrderController {
         return Result.success(result);
     }
 
-    @ApiOperation("订单详情")
+    @ApiOperation(value = "订单详情", notes = "获取订单完整信息。仅能查看自己的订单，查看他人订单会返回权限错误\n\n" +
+            "【关联字典】\n" +
+            "- 返回字段 status → 字典：order_status（订单状态）\n" +
+            "- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态）\n" +
+            "- 返回字段 productType → 字典：product_type（产品类型）\n" +
+            "- 返回字段 travelers[].travelerType → 字典：traveler_type（出行人类型）\n" +
+            "- 返回字段 travelers[].idCardType → 字典：id_card_type（证件类型）\n" +
+            "- 返回字段 travelers[].gender → 字典：gender（性别）\n" +
+            "- 返回字段 timeline[].action → 字典：order_timeline_action（订单操作类型）")
     @GetMapping("/{orderId}")
     public Result<OrderDetailVO> getOrder(HttpServletRequest request,
                                             @ApiParam("订单ID") @PathVariable Long orderId) {

`hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java b/hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java
index 9e92157..1df079f 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java
@@ -12,7 +12,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "内部天气接口(Feign)")
+@Api(tags = "内部天气接口(Feign)", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/weather")
 @RequiredArgsConstructor
@@ -20,21 +20,21 @@ public class MpWeatherController {
 
     private final WeatherService weatherService;
 
-    @ApiOperation("获取订单行程天气")
+    @ApiOperation(value = "获取订单行程天气", notes = "根据订单行程中的城市和日期，批量查询天气信息。返回每天每个城市的天气数据列表")
     @GetMapping("/itinerary/{orderId}")
     public Result<List<Map<String, Object>>> getItineraryWeather(
             @ApiParam("订单ID") @PathVariable Long orderId) {
         return Result.success(weatherService.getItineraryWeather(orderId));
     }
 
-    @ApiOperation("获取指定城市实况天气")
+    @ApiOperation(value = "获取指定城市实况天气", notes = "调用高德天气API查询城市实时天气（温度、湿度、风向等），结果缓存30分钟")
     @GetMapping("/live")
     public Result<WeatherInfo> getLiveWeather(
             @ApiParam("城市名称") @RequestParam String city) {
         return Result.success(weatherService.getLiveWeather(city));
     }
 
-    @ApiOperation("获取指定城市天气预报")
+    @ApiOperation(value = "获取指定城市天气预报", notes = "调用高德天气API查询城市未来3天天气预报，结果缓存2小时")
     @GetMapping("/forecast")
     public Result<WeatherInfo> getForecastWeather(
             @ApiParam("城市名称") @RequestParam String city) {

`hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java
index 8fb0223..48d0a18 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java
@@ -35,7 +35,7 @@ public class AdminCreateOrderRequest {
     @Min(value = 0)
     private int babyCount = 0;
 
-    @ApiModelProperty(value = "儿童是否需要床位", example = "false")
+    @ApiModelProperty(value = "儿童是否需要床位（影响房间分配和报价计算）", example = "false")
     private Boolean childNeedBed = false;
 
     @ApiModelProperty(value = "团期ID(GROUP产品必填)")
@@ -59,14 +59,14 @@ public class AdminCreateOrderRequest {
     @Size(max = 500, message = "备注不能超过500个字符")
     private String remark;
 
-    @ApiModelProperty(value = "用户手机号（可选，用于关联C端用户）", example = "13800138000")
+    @ApiModelProperty(value = "用户手机号（可选，用于关联C端用户）。如匹配到已注册用户则自动绑定订单", example = "13800138000")
     @Size(max = 20)
     private String userPhone;
 
     @ApiModelProperty(value = "定制师ID（可选，默认为创建人）", example = "1760000000000010")
     private Long customizerId;
 
-    @ApiModelProperty(value = "支付时限（分钟），不传则使用全局默认值", example = "30")
+    @ApiModelProperty(value = "支付时限（分钟），不传则使用全局默认值。超时未支付订单自动取消", example = "30")
     @Min(value = 1, message = "支付时限最少1分钟")
     @Max(value = 1440, message = "支付时限最多1440分钟")
     private Integer expiryMinutes;

`hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java
index dfdbe7d..3eb5db1 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java
@@ -11,11 +11,11 @@ import java.math.BigDecimal;
 @Data
 @ApiModel("管理员退款审批请求")
 public class AdminRefundReviewRequest {
-    @ApiModelProperty(value = "审批结果（APPROVE/REJECT）", required = true, example = "APPROVE")
+    @ApiModelProperty(value = "审批结果：APPROVE=通过（自动调起微信退款）、REJECT=拒绝（用户可发起申诉）", required = true, example = "APPROVE")
     @NotBlank(message = "审批结果不能为空")
     private String action;
 
-    @ApiModelProperty(value = "实际退款金额（审批通过时可调整）", example = "1500.00")
+    @ApiModelProperty(value = "实际退款金额（审批通过时可调整，不传则使用申请金额）。不能超过订单已付金额", example = "1500.00")
     private BigDecimal actualAmount;
 
     @ApiModelProperty(value = "审批备注", example = "同意全额退款")

`hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java
index 2d1c10e..44a424e 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java
@@ -44,7 +44,7 @@ public class AdminUpdateOrderRequest {
     @Min(value = 0, message = "幼童数不能为负")
     private Integer babyCount;
 
-    @ApiModelProperty(value = "商户号", example = "1246532201")
+    @ApiModelProperty(value = "商户号（微信支付商户号，多商户场景使用）", example = "1246532201")
     @Size(max = 32, message = "商户号不能超过32个字符")
     private String mchId;
 
@@ -62,6 +62,6 @@ public class AdminUpdateOrderRequest {
 
     // Note: discount is now managed via separate discount CRUD endpoints (POST/PUT/DELETE /admin/order/{orderId}/discount)
 
-    @ApiModelProperty(value = "出行人列表（如提供则替换全部出行人）")
+    @ApiModelProperty(value = "出行人列表（如提供则替换全部出行人，不传则不修改出行人）")
     private List<CreateOrderRequest.TravelerInfo> travelers;
 }

`hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java
index aeb8c8c..b984863 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java
@@ -13,11 +13,12 @@ public class CreateWorkOrderRequest {
     @NotNull(message = "订单ID不能为空")
     private Long orderId;
 
-    @ApiModelProperty(value = "工单类型: ROOM_CHANGE/ROOM_ADD/CHECKOUT_CHANGE/HOTEL_ISSUE/VEHICLE_CHANGE/SCENIC_ADD/SCENIC_REMOVE/OTHER", required = true)
+    @ApiModelProperty(value = "工单类型: ROOM_CHANGE(换房)/ROOM_ADD(加房)/CHECKOUT_CHANGE(改退房日期)/" +
+            "HOTEL_ISSUE(酒店问题)/VEHICLE_CHANGE(换车)/SCENIC_ADD(加景点)/SCENIC_REMOVE(减景点)/OTHER(其他)", required = true)
     @NotBlank(message = "工单类型不能为空")
     private String type;
 
-    @ApiModelProperty(value = "优先级: URGENT/NORMAL", required = true)
+    @ApiModelProperty(value = "优先级: URGENT(紧急，如当天出发需处理)/NORMAL(普通)", required = true)
     @NotBlank(message = "优先级不能为空")
     private String priority;
 
@@ -31,7 +32,7 @@ public class CreateWorkOrderRequest {
     @ApiModelProperty("资源详情JSON(酒店/车辆/景点信息)")
     private String resourceDetail;
 
-    @ApiModelProperty("差价(正数=加价, 负数=退费)")
+    @ApiModelProperty("差价(正数=客户需补差价, 负数=需退费给客户)")
     private BigDecimal costDifference;
 
     @ApiModelProperty("指定处理人ID")

`hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java
index f2f451c..a678aff 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/EarlyBirdPlanRequest.java
@@ -24,12 +24,12 @@ public class EarlyBirdPlanRequest {
     @NotNull(message = "生效结束日期不能为空")
     private LocalDate endDate;
 
-    @ApiModelProperty(value = "最低人数", required = true, example = "2")
+    @ApiModelProperty(value = "最低出行人数（含成人+儿童），订单人数>=此值才能享受优惠", required = true, example = "2")
     @NotNull(message = "最低人数不能为空")
     @Min(value = 1, message = "最低人数至少为1")
     private Integer minPeople;
 
-    @ApiModelProperty(value = "优惠金额", required = true, example = "200.00")
+    @ApiModelProperty(value = "优惠金额（从订单总价中扣减的固定金额）", required = true, example = "200.00")
     @NotNull(message = "优惠金额不能为空")
     @DecimalMin(value = "0.01", message = "优惠金额必须大于0")
     private BigDecimal discountAmount;

`hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java
index 125cd6a..9a93336 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java
@@ -13,7 +13,7 @@ public class InvoiceApplyRequest {
     @NotNull(message = "orderId is required")
     private Long orderId;
 
-    @ApiModelProperty(value = "抬头类型（personal=个人/company=企业）", example = "personal")
+    @ApiModelProperty(value = "抬头类型：personal=个人（默认）、company=企业（需填写税号）", example = "personal")
     private String titleType = "personal";
 
     @ApiModelProperty(value = "发票抬头", required = true, example = "张三")

`hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java
index 98b28d5..c28453b 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/MpOrderQueryRequest.java
@@ -10,7 +10,7 @@ import javax.validation.constraints.Min;
 @Data
 @ApiModel("C端订单查询请求")
 public class MpOrderQueryRequest {
-    @ApiModelProperty(value = "订单状态", example = "PAID")
+    @ApiModelProperty(value = "订单状态（不传则查全部）。可选值：PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/PENDING_BALANCE/PENDING_DEPARTURE/TRAVELLING/COMPLETED/AFTER_SALE/REFUNDING/REFUNDED/CANCELLED", example = "PAID")
     private String status;
 
     @ApiModelProperty(value = "页码", example = "1")

`hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java
index 9782f64..0b13f71 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java
@@ -9,12 +9,12 @@ import java.time.LocalDate;
 import java.util.List;
 
 @Data
-@ApiModel("小程序修改订单请求")
+@ApiModel(value = "小程序修改订单请求", description = "用户可修改出发日期和出行人。修改后系统自动重算价格，内部流程已启动的订单会通知定制师")
 public class MpUpdateOrderRequest {
 
-    @ApiModelProperty(value = "出发日期", example = "2026-05-01")
+    @ApiModelProperty(value = "出发日期（修改出发日期会触发价格重算）", example = "2026-05-01")
     private LocalDate departureDate;
 
-    @ApiModelProperty(value = "出行人列表（如提供则替换全部出行人）")
+    @ApiModelProperty(value = "出行人列表（如提供则替换全部出行人，不传则不修改出行人）")
     private List<CreateOrderRequest.TravelerInfo> travelers;
 }

`hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java
index 4d8aa75..7c32a24 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java
@@ -11,11 +11,11 @@ import javax.validation.constraints.Size;
 @Data
 @ApiModel("退款申请请求")
 public class RefundApplyRequest {
-    @ApiModelProperty(value = "退款类型（字典：refund_type）", required = true, example = "FULL")
+    @ApiModelProperty(value = "退款类型：FULL=全额退款、PARTIAL=部分退款", required = true, example = "FULL")
     @NotBlank(message = "退款类型不能为空")
     private String refundType;
 
-    @ApiModelProperty(value = "退款原因ID", example = "1760000000000001")
+    @ApiModelProperty(value = "退款原因ID（从退款原因列表接口获取）", example = "1760000000000001")
     private Long reasonId;
 
     @ApiModelProperty(value = "退款原因", required = true, example = "行程有变，无法出行")

`hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java
index cb0873c..a6a18a7 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java
@@ -42,12 +42,12 @@ public class RefundPolicyRequest {
     @Data
     @ApiModel("退款规则项")
     public static class RuleItem {
-        @ApiModelProperty(value = "距出发最少天数", required = true, example = "7")
+        @ApiModelProperty(value = "距出发最少天数（含当天）。例如：minDays=7表示出发前7天及以上适用此规则", required = true, example = "7")
         @NotNull(message = "最少天数不能为空")
         @Min(value = 0, message = "最少天数不能小于0")
         private Integer minDays;
 
-        @ApiModelProperty(value = "退款比例（百分比）", required = true, example = "80")
+        @ApiModelProperty(value = "退款比例（百分比，0-100）。例如：80表示退已付金额的80%", required = true, example = "80")
         @NotNull(message = "退款比例不能为空")
         @Min(value = 0, message = "退款比例不能小于0")
         @Max(value = 100, message = "退款比例不能超过100")

`hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java b/hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java
index f290109..c40fb91 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java
@@ -9,7 +9,10 @@ import javax.validation.constraints.NotBlank;
 @Data
 @ApiModel("更新订单状态请求")
 public class UpdateOrderStatusRequest {
-    @ApiModelProperty(value = "目标状态（字典：order_status）", required = true, example = "CONFIRMED")
+    @ApiModelProperty(value = "目标状态。可选值：PENDING_PAY(待支付)/DEPOSIT_PAID(已付定金)/PAID(已全额支付)/" +
+            "CONFIRMED(已确认)/PENDING_BALANCE(待付尾款)/PENDING_DEPARTURE(待出行)/" +
+            "TRAVELLING(旅行中)/COMPLETED(已完成)/AFTER_SALE(售后中)/REFUNDING(退款中)/" +
+            "REFUNDED(已退款)/CANCELLED(已取消)", required = true, example = "CONFIRMED")
     @NotBlank(message = "状态不能为空")
     private String status;
 }

`hl-order-service/src/main/java/com/hulalv/order/service/WeatherService.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/service/WeatherService.java b/hl-order-service/src/main/java/com/hulalv/order/service/WeatherService.java
index 74d4a55..f5b652e 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/service/WeatherService.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/service/WeatherService.java
@@ -127,7 +127,11 @@ public class WeatherService {
      * 获取指定城市的天气预报（带缓存）
      */
     public WeatherInfo getCachedForecast(String cityName) {
-        if (!StringUtils.hasText(cityName) || !StringUtils.hasText(amapKey)) {
+        if (!StringUtils.hasText(amapKey)) {
+            log.error("天气服务未配置: amap.key为空");
+            return null;
+        }
+        if (!StringUtils.hasText(cityName)) {
             return null;
         }
         String cacheKey = WEATHER_CACHE_PREFIX + cityName;
@@ -141,7 +145,10 @@ public class WeatherService {
         }
 
         String adcode = getCachedAdcode(cityName);
-        if (adcode == null) return null;
+        if (adcode == null) {
+            log.warn("无法获取城市adcode: city={}, 可能是城市名不正确或API Key无效", cityName);
+            return null;
+        }
 
         WeatherInfo weather = amapWeatherClient.getForecastWeather(adcode, amapKey);
         if (weather != null) {

`hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java` (M)

diff --git a/hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java b/hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java
index 58106e0..f6bcd64 100644
--- a/hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java
+++ b/hl-order-service/src/main/java/com/hulalv/order/vo/WorkOrderVO.java
@@ -82,12 +82,24 @@ public class WorkOrderVO {
     private List<WorkOrderLogVO> logs;
 
     @Data
+    @io.swagger.annotations.ApiModel("工单操作日志VO")
     public static class WorkOrderLogVO {
+        @ApiModelProperty("日志ID")
         private String logId;
+
+        @ApiModelProperty("操作动作")
         private String action;
+
+        @ApiModelProperty("操作动作标签")
         private String actionLabel;
+
+        @ApiModelProperty("操作内容")
         private String content;
+
+        @ApiModelProperty("操作人姓名")
         private String operatorName;
+
+        @ApiModelProperty("操作时间")
         private LocalDateTime createdAt;
     }
 }

`hl-payment-service/src/main/java/com/hulalv/payment/config/Knife4jConfig.java` (M)

diff --git a/hl-payment-service/src/main/java/com/hulalv/payment/config/Knife4jConfig.java b/hl-payment-service/src/main/java/com/hulalv/payment/config/Knife4jConfig.java
index 35ae74b..be0e684 100644
--- a/hl-payment-service/src/main/java/com/hulalv/payment/config/Knife4jConfig.java
+++ b/hl-payment-service/src/main/java/com/hulalv/payment/config/Knife4jConfig.java
@@ -1,9 +1,9 @@
 package com.hulalv.payment.config;
 
+import com.google.common.base.Predicate;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
-import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
@@ -11,6 +11,11 @@ import springfox.documentation.spring.web.plugins.Docket;
 @Configuration
 public class Knife4jConfig {
 
+    /** 排除内部接口和回调接口路径 */
+    private Predicate<String> adminPaths() {
+        return input -> input != null && !input.contains("/internal/") && !input.contains("/callback/");
+    }
+
     @Bean
     public Docket paymentApi() {
         return new Docket(DocumentationType.SWAGGER_2)
@@ -22,7 +27,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.payment.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 }

`hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java` (M)

diff --git a/hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java b/hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java
index 3392e72..10a9ea4 100644
--- a/hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java
+++ b/hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java
@@ -27,13 +27,13 @@ public class AdminPaymentController {
     private final RefundService refundService;
 
     @GetMapping("/list")
-    @ApiOperation(value = "支付交易列表", notes = "分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选")
+    @ApiOperation(value = "支付交易列表", notes = "分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选\n\n**关联字典**：\n- payment_mode：支付模式（列表筛选+显示）")
     public Result<PageResult<PaymentVO>> listTransactions(@ApiParam("支付查询条件") @Valid PaymentQueryRequest request) {
         return Result.success(paymentService.listTransactions(request));
     }
 
     @GetMapping("/{transactionId}")
-    @ApiOperation(value = "交易详情", notes = "获取单笔交易的完整信息，包含微信支付流水号")
+    @ApiOperation(value = "交易详情", notes = "获取单笔交易的完整信息，包含微信支付流水号\n\n**关联字典**：\n- payment_mode：支付模式（显示）")
     public Result<PaymentVO> getDetail(@ApiParam("交易ID") @PathVariable Long transactionId) {
         return Result.success(paymentService.getDetail(transactionId));
     }

`hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java` (M)

diff --git a/hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java b/hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java
index d195a48..dbdfc84 100644
--- a/hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java
+++ b/hl-payment-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java
@@ -25,14 +25,14 @@ import java.util.List;
 @RestController
 @RequestMapping("/internal/payment")
 @RequiredArgsConstructor
-@Api(tags = "【内部接口】支付（Feign调用）")
+@Api(tags = "【内部接口】支付（Feign调用）", hidden = true)
 public class InternalPaymentController {
 
     private final PaymentService paymentService;
     private final RefundService refundService;
 
     @PostMapping("/prepay")
-    @ApiOperation("Create prepay order (called by BFF)")
+    @ApiOperation(value = "创建预支付订单", notes = "由BFF层调用，向微信支付API发起预支付请求，返回前端调起支付所需的参数（prepay_id等）")
     public Result<PrepayResponse> prepay(
             @RequestParam("userId") Long userId,
             @Valid @RequestBody PrepayRequest request) {
@@ -41,7 +41,7 @@ public class InternalPaymentController {
     }
 
     @GetMapping("/status/{orderId}")
-    @ApiOperation("Query payment status (called by BFF)")
+    @ApiOperation(value = "查询支付状态", notes = "查询订单的支付状态，含用户权限校验（userId不匹配时拒绝访问）\n\n**关联字典**：\n- payment_status：支付状态（返回字段）")
     public Result<PaymentVO> getStatus(@RequestParam(value = "userId", required = false) Long userId,
                                         @PathVariable Long orderId) {
         PaymentVO vo = paymentService.getPaymentStatus(orderId);
@@ -53,7 +53,7 @@ public class InternalPaymentController {
     }
 
     @GetMapping("/transactions/{orderId}")
-    @ApiOperation("List all transactions for an order (called by BFF)")
+    @ApiOperation(value = "订单交易记录列表", notes = "查询指定订单的所有支付交易记录（含支付和退款），含用户权限校验\n\n**关联字典**：\n- payment_status：支付状态（返回字段）")
     public Result<List<PaymentVO>> listTransactions(@RequestParam(value = "userId", required = false) Long userId,
                                                      @PathVariable Long orderId) {
         List<PaymentVO> list = paymentService.listByOrder(orderId);
@@ -67,7 +67,7 @@ public class InternalPaymentController {
     }
 
     @PostMapping("/refund")
-    @ApiOperation("Create refund (called by order-service)")
+    @ApiOperation(value = "创建退款", notes = "由订单服务调用，向微信支付API发起退款请求。退款金额不能超过原支付金额，退款结果通过微信回调异步通知")
     public Result<RefundVO> createRefund(@Valid @RequestBody PaymentRefundRequest refundRequest) {
         RefundRequest request = new RefundRequest();
         request.setOrderId(refundRequest.getOrderId());

`hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java` (M)

diff --git a/hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java b/hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java
index d950113..8b8106b 100644
--- a/hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java
+++ b/hl-payment-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java
@@ -23,14 +23,14 @@ import java.util.Map;
 @RestController
 @RequestMapping("/pay/callback")
 @RequiredArgsConstructor
-@Api(tags = "【回调接口】支付回调")
+@Api(tags = "【回调接口】支付回调", hidden = true)
 public class PaymentCallbackController {
 
     private final PaymentService paymentService;
     private final RefundService refundService;
 
     @PostMapping("/notify/{mchId}")
-    @ApiOperation("支付成功回调")
+    @ApiOperation(value = "支付成功回调", notes = "微信支付成功后的异步通知回调（无需认证，通过微信签名验证安全性）。验证签名 → 更新支付状态 → 发送MQ消息通知订单服务")
     public ResponseEntity<Map<String, String>> payNotify(
             @PathVariable String mchId,
             HttpServletRequest request) {
@@ -49,7 +49,7 @@ public class PaymentCallbackController {
     }
 
     @PostMapping("/refund-notify/{mchId}")
-    @ApiOperation("退款回调")
+    @ApiOperation(value = "退款回调", notes = "微信退款结果的异步通知回调（无需认证，通过微信签名验证安全性）。验证签名 → 更新退款状态 → 发送MQ消息通知订单服务")
     public ResponseEntity<Map<String, String>> refundNotify(
             @PathVariable String mchId,
             HttpServletRequest request) {

`hl-product-service/src/main/java/com/hulalv/product/config/Knife4jConfig.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/config/Knife4jConfig.java b/hl-product-service/src/main/java/com/hulalv/product/config/Knife4jConfig.java
index 746c86e..f483fa8 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/config/Knife4jConfig.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/config/Knife4jConfig.java
@@ -1,9 +1,9 @@
 package com.hulalv.product.config;
 
+import com.google.common.base.Predicate;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
-import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
@@ -11,6 +11,11 @@ import springfox.documentation.spring.web.plugins.Docket;
 @Configuration
 public class Knife4jConfig {
 
+    /** 排除内部接口和回调接口路径 */
+    private Predicate<String> adminPaths() {
+        return input -> input != null && !input.contains("/internal/") && !input.contains("/callback/");
+    }
+
     @Bean
     public Docket productApi() {
         return new Docket(DocumentationType.SWAGGER_2)
@@ -22,7 +27,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.product.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 }

`hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java
index 3d92709..5a21261 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/DistrictController.java
@@ -21,7 +21,12 @@ public class DistrictController {
 
     private final AmapDistrictService amapDistrictService;
 
-    @ApiOperation("搜索行政区划（城市/区县）")
+    @ApiOperation(value = "搜索行政区划（城市/区县）",
+            notes = "通过高德地图 API 搜索行政区划，用于产品的出发城市和目的地城市选择。\n"
+                    + "输入关键词（如\"丽江\"、\"昆明\"），返回匹配的城市/区县列表，包含行政区划编码。\n\n"
+                    + "**关联字典**：\n"
+                    + "- cities（城市）：搜索结果可用于产品行程中的城市预览\n"
+                    + "- city（城市筛选）：搜索结果可用于资源面板城市筛选")
     @GetMapping("/search")
     public Result<List<AmapDistrictService.DistrictItem>> search(
             @ApiParam("搜索关键词") @RequestParam String keywords) {

`hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java
index b1bba5b..8e8827f 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/FamilyController.java
@@ -21,13 +21,19 @@ public class FamilyController {
 
     private final ProductFamilyService familyService;
 
-    @ApiOperation("获取家庭分组列表")
+    @ApiOperation(value = "获取家庭分组列表",
+            notes = "获取产品的家庭分组列表，按排序序号升序。\n\n"
+                    + "**仅适用于 CUSTOM（定制）产品**。\n"
+                    + "家庭分组用于将定制产品的行程按家庭单位分配，每个家庭可以有不同的人数和行程安排。\n"
+                    + "行程节点通过 familyIds 字段关联到具体的家庭分组。")
     @GetMapping("/families")
     public Result<List<ProductFamilyVO>> listFamilies(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(familyService.listFamilies(productId));
     }
 
-    @ApiOperation("添加家庭分组")
+    @ApiOperation(value = "添加家庭分组",
+            notes = "为 CUSTOM 定制产品添加一个家庭分组，指定家庭名称和各类型人数。\n"
+                    + "添加后可在行程节点中关联此家庭，实现按家庭分配行程。")
     @PostMapping("/family")
     public Result<ProductFamilyVO> addFamily(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -35,7 +41,9 @@ public class FamilyController {
         return Result.success(familyService.addFamily(productId, request));
     }
 
-    @ApiOperation("更新家庭分组")
+    @ApiOperation(value = "更新家庭分组",
+            notes = "更新家庭分组的名称、各类型人数等信息。\n"
+                    + "**仅适用于 CUSTOM（定制）产品**。")
     @PutMapping("/family/{familyId}")
     public Result<ProductFamilyVO> updateFamily(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -44,7 +52,9 @@ public class FamilyController {
         return Result.success(familyService.updateFamily(familyId, request));
     }
 
-    @ApiOperation("删除家庭分组")
+    @ApiOperation(value = "删除家庭分组",
+            notes = "删除家庭分组。如果有行程节点通过 familyIds 关联了该分组，需要手动移除关联。\n"
+                    + "**仅适用于 CUSTOM（定制）产品**。")
     @DeleteMapping("/family/{familyId}")
     public Result<Void> deleteFamily(
             @ApiParam("产品ID") @PathVariable Long productId,

`hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java
index 9d4395e..6cc32f3 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/FormulaController.java
@@ -32,20 +32,34 @@ public class FormulaController {
 
     // ===== Group endpoints =====
 
-    @ApiOperation("公式组列表")
+    @ApiOperation(value = "公式组列表",
+            notes = "获取定价公式组列表，可按产品类型筛选。\n\n"
+                    + "**公式引擎说明**：定价公式用于自动计算产品的成本价和售价。\n"
+                    + "每种产品类型可以有多个公式组，但同一时间只能有一个激活的公式组。\n"
+                    + "公式组包含多个步骤，按顺序执行，每步计算一个中间变量或最终结果。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，筛选条件）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/group/list")
     public Result<List<FormulaGroupVO>> listGroups(
             @RequestParam(required = false) String productType) {
         return Result.success(groupService.listGroups(productType));
     }
 
-    @ApiOperation("公式组详情")
+    @ApiOperation(value = "公式组详情",
+            notes = "获取公式组完整信息。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/group/{groupId}")
     public Result<FormulaGroupVO> getGroup(@PathVariable Long groupId) {
         return Result.success(groupService.getGroup(groupId));
     }
 
-    @ApiOperation("创建公式组")
+    @ApiOperation(value = "创建公式组",
+            notes = "创建一个新的定价公式组。创建后默认为未激活状态。\n\n"
+                    + "公式组编码（groupCode）在同一产品类型下必须唯一。\n"
+                    + "建议命名规范：{产品类型}_PRICING_V{版本号}，如 CORE_PRICING_V2。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，公式组所属类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PostMapping("/group")
     public Result<FormulaGroupVO> createGroup(@Valid @RequestBody FormulaGroupRequest request,
                                                HttpServletRequest httpRequest) {
@@ -53,21 +67,31 @@ public class FormulaController {
         return Result.success(groupService.createGroup(request, adminId));
     }
 
-    @ApiOperation("更新公式组")
+    @ApiOperation(value = "更新公式组",
+            notes = "更新公式组信息。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PutMapping("/group/{groupId}")
     public Result<FormulaGroupVO> updateGroup(@PathVariable Long groupId,
                                                @Valid @RequestBody FormulaGroupRequest request) {
         return Result.success(groupService.updateGroup(groupId, request));
     }
 
-    @ApiOperation("激活公式组")
+    @ApiOperation(value = "激活公式组",
+            notes = "激活指定公式组，同时自动停用同产品类型下的其他公式组。\n\n"
+                    + "同一产品类型下只能有一个激活的公式组，激活操作具有排他性。\n"
+                    + "激活后，该产品类型的自动成本计算将使用此公式组。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，同类型排他激活）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PutMapping("/group/{groupId}/activate")
     public Result<Void> activateGroup(@PathVariable Long groupId) {
         groupService.activateGroup(groupId);
         return Result.success();
     }
 
-    @ApiOperation("删除公式组")
+    @ApiOperation(value = "删除公式组",
+            notes = "删除公式组及其下所有步骤。\n"
+                    + "**限制**：已激活的公式组不能删除，需先激活其他公式组。")
     @DeleteMapping("/group/{groupId}")
     public Result<Void> deleteGroup(@PathVariable Long groupId) {
         groupService.deleteGroup(groupId);
@@ -76,25 +100,35 @@ public class FormulaController {
 
     // ===== Step endpoints =====
 
-    @ApiOperation("公式步骤列表")
+    @ApiOperation(value = "公式步骤列表",
+            notes = "获取公式组下所有步骤，按执行顺序（executionOrder）升序排列。\n"
+                    + "步骤按顺序依次执行，前一步的输出变量可作为后续步骤的输入。")
     @GetMapping("/group/{groupId}/steps")
     public Result<List<FormulaStepVO>> listSteps(@PathVariable Long groupId) {
         return Result.success(stepService.listSteps(groupId));
     }
 
-    @ApiOperation("公式步骤详情")
+    @ApiOperation(value = "公式步骤详情",
+            notes = "获取单个公式步骤的完整信息，包含表达式、输入/输出变量、执行顺序等。")
     @GetMapping("/step/{formulaId}")
     public Result<FormulaStepVO> getStep(@PathVariable Long formulaId) {
         return Result.success(stepService.getStep(formulaId));
     }
 
-    @ApiOperation("创建公式步骤")
+    @ApiOperation(value = "创建公式步骤",
+            notes = "在公式组中创建一个计算步骤。\n\n"
+                    + "**表达式语法**：使用 Aviator 表达式引擎，支持数学运算、条件判断、内置函数等。\n"
+                    + "示例：`baseCost = adultCount * adultUnitCost + childCount * childUnitCost`\n\n"
+                    + "**输入变量**：可引用公式变量表中定义的变量，或前置步骤的输出变量。\n"
+                    + "**输出变量**：每个步骤必须指定一个输出变量名，供后续步骤引用。")
     @PostMapping("/step")
     public Result<FormulaStepVO> createStep(@Valid @RequestBody FormulaStepRequest request) {
         return Result.success(stepService.createStep(request));
     }
 
-    @ApiOperation("更新公式步骤")
+    @ApiOperation(value = "更新公式步骤",
+            notes = "更新公式步骤的表达式、输入/输出变量等。\n"
+                    + "每次更新会自动保存一个版本快照，可通过版本历史接口查看和回滚。")
     @PutMapping("/step/{formulaId}")
     public Result<FormulaStepVO> updateStep(@PathVariable Long formulaId,
                                              @Valid @RequestBody FormulaStepRequest request,
@@ -103,27 +137,36 @@ public class FormulaController {
         return Result.success(stepService.updateStep(formulaId, request, adminId));
     }
 
-    @ApiOperation("启用/禁用公式步骤")
+    @ApiOperation(value = "启用/禁用公式步骤",
+            notes = "切换公式步骤的启用状态。\n"
+                    + "禁用的步骤在公式执行时会被跳过，不影响其他步骤的执行。\n"
+                    + "适用场景：临时跳过某个计算步骤进行调试或测试。")
     @PutMapping("/step/{formulaId}/toggle")
     public Result<Void> toggleStep(@PathVariable Long formulaId) {
         stepService.toggleStep(formulaId);
         return Result.success();
     }
 
-    @ApiOperation("删除公式步骤")
+    @ApiOperation(value = "删除公式步骤",
+            notes = "删除指定的公式步骤。删除后其他步骤的执行顺序不会自动调整。\n"
+                    + "**注意**：如果后续步骤引用了被删步骤的输出变量，执行时会报错。")
     @DeleteMapping("/step/{formulaId}")
     public Result<Void> deleteStep(@PathVariable Long formulaId) {
         stepService.deleteStep(formulaId);
         return Result.success();
     }
 
-    @ApiOperation("公式步骤版本历史")
+    @ApiOperation(value = "公式步骤版本历史",
+            notes = "获取公式步骤的所有历史版本列表，按版本号倒序。\n"
+                    + "每次更新步骤表达式会自动创建新版本，方便追溯和回滚。")
     @GetMapping("/step/{formulaId}/versions")
     public Result<List<FormulaVersionVO>> listVersions(@PathVariable Long formulaId) {
         return Result.success(stepService.listVersions(formulaId));
     }
 
-    @ApiOperation("回滚公式步骤到指定版本")
+    @ApiOperation(value = "回滚公式步骤到指定版本",
+            notes = "将公式步骤回滚到历史版本。\n"
+                    + "回滚操作会用历史版本的表达式、变量等覆盖当前内容，并创建一个新的版本记录。")
     @PutMapping("/step/{formulaId}/rollback/{versionNum}")
     public Result<FormulaStepVO> rollbackStep(@PathVariable Long formulaId,
                                                @PathVariable Integer versionNum,
@@ -134,7 +177,11 @@ public class FormulaController {
 
     // ===== Test endpoint =====
 
-    @ApiOperation("测试公式执行")
+    @ApiOperation(value = "测试公式执行",
+            notes = "使用自定义变量值测试公式组的执行结果，不影响任何业务数据。\n\n"
+                    + "传入公式组ID和测试变量（变量名→值的映射），返回每个步骤的执行结果。\n"
+                    + "适用于公式调试：验证表达式是否正确、计算结果是否符合预期。\n"
+                    + "如果某步骤执行出错，会在结果中标明错误信息。")
     @PostMapping("/test")
     public Result<FormulaTestResultVO> testFormulas(@Valid @RequestBody FormulaTestRequest request) {
         return Result.success(testService.testFormulas(request));
@@ -142,27 +189,41 @@ public class FormulaController {
 
     // ===== Var endpoints =====
 
-    @ApiOperation("公式变量列表")
+    @ApiOperation(value = "公式变量列表",
+            notes = "获取公式变量列表，可按变量分类筛选。\n\n"
+                    + "**变量分类**：\n"
+                    + "- INPUT：输入变量，从业务数据获取（如成人人数、资源单价）\n"
+                    + "- INTERMEDIATE：中间变量，由公式步骤计算得出\n"
+                    + "- OUTPUT：输出变量，最终报价结果（如总成本、售价）")
     @GetMapping("/var/list")
     public Result<List<FormulaVarVO>> listVars(
             @RequestParam(required = false) String category) {
         return Result.success(varService.listVars(category));
     }
 
-    @ApiOperation("创建公式变量")
+    @ApiOperation(value = "创建公式变量",
+            notes = "创建公式变量定义。变量名（varName）全局唯一，建议使用驼峰命名。\n"
+                    + "可指定适用的产品类型列表（productTypes），为空则适用于所有类型。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，变量适用范围）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PostMapping("/var")
     public Result<FormulaVarVO> createVar(@Valid @RequestBody FormulaVarRequest request) {
         return Result.success(varService.createVar(request));
     }
 
-    @ApiOperation("更新公式变量")

`hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java
index 7e553dc..ab7b818 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/GroupBatchController.java
@@ -25,7 +25,16 @@ public class GroupBatchController {
 
     // ===== Batch CRUD =====
 
-    @ApiOperation("创建主批次")
+    @ApiOperation(value = "创建主批次",
+            notes = "为 GROUP（小蒙马拼团）产品创建一个团期主批次。\n\n"
+                    + "**仅适用于 GROUP 产品类型**。\n"
+                    + "每个批次有独立的出发日期、报名截止日期、人数上限。\n"
+                    + "创建后状态为 PENDING（待开放），需手动开启报名。\n\n"
+                    + "**批次状态流转**：PENDING → ENROLLING（报名中）→ CONFIRMED（已成团）→ CLOSED（已关闭）\n"
+                    + "任意报名状态均可被解散（DISBANDED）。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，仅限GROUP）：GROUP=小蒙马拼团\n"
+                    + "- batch_status（批次状态）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束")
     @PostMapping
     public Result<GroupTourBatchVO> createBatch(@PathVariable Long productId,
                                                 @Valid @RequestBody GroupBatchCreateRequest request,
@@ -34,7 +43,11 @@ public class GroupBatchController {
         return Result.success(batchService.createBatch(productId, request, adminId));
     }
 
-    @ApiOperation("创建子批次(溢出)")
+    @ApiOperation(value = "创建子批次(溢出)",
+            notes = "当主批次人数满员时，创建子批次接收溢出报名。\n\n"
+                    + "子批次共享主批次的出发日期和行程，但有独立的人数上限和报名人数。\n"
+                    + "适用场景：某团期特别火爆，需要扩容但希望分开管理。\n"
+                    + "子批次在列表中显示为主批次的子级节点。")
     @PostMapping("/{batchId}/sub-batch")
     public Result<GroupTourBatchVO> createSubBatch(@PathVariable Long productId,
                                                     @PathVariable Long batchId,
@@ -44,7 +57,9 @@ public class GroupBatchController {
         return Result.success(batchService.createSubBatch(batchId, request, adminId));
     }
 
-    @ApiOperation("更新批次")
+    @ApiOperation(value = "更新批次",
+            notes = "更新批次基本信息。仅传入需要修改的字段。\n"
+                    + "已有报名人员的批次修改人数上限时，不能低于已报名人数。")
     @PutMapping("/{batchId}")
     public Result<GroupTourBatchVO> updateBatch(@PathVariable Long productId,
                                                 @PathVariable Long batchId,
@@ -52,20 +67,30 @@ public class GroupBatchController {
         return Result.success(batchService.updateBatch(batchId, request));
     }
 
-    @ApiOperation("删除批次")
+    @ApiOperation(value = "删除批次",
+            notes = "删除批次（软删除）。\n"
+                    + "**限制**：已有报名人员的批次不能直接删除，需先解散批次。")
     @DeleteMapping("/{batchId}")
     public Result<Void> deleteBatch(@PathVariable Long productId, @PathVariable Long batchId) {
         batchService.deleteBatch(batchId);
         return Result.success();
     }
 
-    @ApiOperation("批次列表(树形)")
+    @ApiOperation(value = "批次列表(树形)",
+            notes = "获取产品所有批次，以树形结构返回（主批次包含子批次列表）。\n"
+                    + "按出发日期升序排列，包含每个批次的报名人数和剩余名额。\n\n"
+                    + "**关联字典**：\n"
+                    + "- batch_status（批次状态，返回字段）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束")
     @GetMapping("/list")
     public Result<List<GroupTourBatchVO>> listBatches(@PathVariable Long productId) {
         return Result.success(batchService.listBatches(productId));
     }
 
-    @ApiOperation("批次详情")
+    @ApiOperation(value = "批次详情",
+            notes = "获取单个批次的完整信息，包括批次基本信息、服务人员配置、套餐组合等。\n\n"
+                    + "**关联字典**：\n"
+                    + "- batch_status（批次状态）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束\n"
+                    + "- staff_type（人员类型，服务人员配置）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他")
     @GetMapping("/{batchId}")
     public Result<GroupTourBatchDetailVO> getBatchDetail(@PathVariable Long productId,
                                                          @PathVariable Long batchId) {
@@ -74,21 +99,33 @@ public class GroupBatchController {
 
     // ===== Status operations =====
 
-    @ApiOperation("开启报名(PENDING->ENROLLING)")
+    @ApiOperation(value = "开启报名(PENDING->ENROLLING)",
+            notes = "将批次从 PENDING 状态变更为 ENROLLING（报名中）。\n"
+                    + "开启后用户可在小程序端看到该团期并报名。\n"
+                    + "前提条件：产品必须已上架（PUBLISHED）。")
     @PutMapping("/{batchId}/open")
     public Result<Void> openEnrollment(@PathVariable Long productId, @PathVariable Long batchId) {
         batchService.openEnrollment(batchId);
         return Result.success();
     }
 
-    @ApiOperation("关闭报名(ENROLLING/CONFIRMED->CLOSED)")
+    @ApiOperation(value = "关闭报名(ENROLLING/CONFIRMED->CLOSED)",
+            notes = "关闭批次报名，不再接受新的报名。\n"
+                    + "已报名的订单不受影响，仅阻止新增报名。\n"
+                    + "适用于报名截止日期到达或手动提前关闭的场景。")
     @PutMapping("/{batchId}/close")
     public Result<Void> closeEnrollment(@PathVariable Long productId, @PathVariable Long batchId) {
         batchService.closeEnrollment(batchId);
         return Result.success();
     }
 
-    @ApiOperation("解散批次")
+    @ApiOperation(value = "解散批次",
+            notes = "解散批次并处理已报名的订单。\n\n"
+                    + "**重要**：解散操作会触发以下流程：\n"
+                    + "1. 批次状态变更为 DISBANDED\n"
+                    + "2. 通过 MQ 消息通知订单服务，自动取消该批次下的所有未完成订单\n"
+                    + "3. 已支付订单会触发退款流程\n\n"
+                    + "必须填写解散原因（如：报名人数不足、行程调整等）。")
     @PostMapping("/{batchId}/disband")
     public Result<Void> disbandBatch(@PathVariable Long productId,
                                       @PathVariable Long batchId,
@@ -103,7 +140,13 @@ public class GroupBatchController {
 
     // ===== Staff operations =====
 
-    @ApiOperation("保存服务人员(全量替换)")
+    @ApiOperation(value = "保存服务人员(全量替换)",
+            notes = "保存批次的服务人员配置，采用全量替换模式（先删后增）。\n\n"
+                    + "每次提交完整的人员列表，替换掉该批次原有的所有人员配置。\n"
+                    + "人员来源于资源服务的人员库，通过 staffId 关联。\n"
+                    + "**角色类型**：LEADER(领队)/PHOTOGRAPHER(摄影师)/DRIVER(司机)/OTHER(其他)\n\n"
+                    + "**关联字典**：\n"
+                    + "- staff_type（人员类型）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他")
     @PostMapping("/{batchId}/staff")
     public Result<List<GroupBatchStaffVO>> saveStaff(@PathVariable Long productId,
                                                      @PathVariable Long batchId,
@@ -111,14 +154,18 @@ public class GroupBatchController {
         return Result.success(staffService.saveStaff(batchId, productId, requests));
     }
 
-    @ApiOperation("服务人员列表")
+    @ApiOperation(value = "服务人员列表",
+            notes = "**关联字典**：\n"
+                    + "- staff_type（人员类型）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他")
     @GetMapping("/{batchId}/staff")
     public Result<List<GroupBatchStaffVO>> listStaff(@PathVariable Long productId,
                                                      @PathVariable Long batchId) {
         return Result.success(staffService.listStaff(batchId));
     }
 
-    @ApiOperation("从其他批次复制服务人员")
+    @ApiOperation(value = "从其他批次复制服务人员",
+            notes = "将源批次的服务人员配置复制到当前批次（全量替换当前批次已有人员）。\n"
+                    + "适用场景：多个团期使用相同的服务人员班底。")
     @PostMapping("/{batchId}/staff/copy-from/{sourceId}")
     public Result<List<GroupBatchStaffVO>> copyStaff(@PathVariable Long productId,
                                                      @PathVariable Long batchId,

`hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java
index 61d9a75..7a6ea65 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java
@@ -36,7 +36,7 @@ import java.util.Map;
  * C端产品内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "【内部接口】小程序产品（Feign调用）")
+@Api(tags = "【内部接口】小程序产品（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/product")
 @RequiredArgsConstructor
@@ -50,39 +50,56 @@ public class InternalMpProductController {
     private final ProductPriceCalendarMapper priceCalendarMapper;
     private final GroupTourBatchMapper groupTourBatchMapper;
 
-    @ApiOperation("产品列表")
+    @ApiOperation(value = "产品列表",
+            notes = "内部Feign接口，返回已上架产品列表。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，筛选+返回字段）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/list")
     public Result<PageResult<MpProductListVO>> listProducts(@Valid MpProductQueryRequest query) {
         return Result.success(productService.listPublishedProducts(query));
     }
 
-    @ApiOperation("产品详情")
+    @ApiOperation(value = "产品详情",
+            notes = "内部Feign接口，返回已上架产品详情。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态）：PUBLISHED=已上架\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @GetMapping("/{productId}")
     public Result<ProductVO> getProduct(@PathVariable Long productId) {
         return Result.success(productService.getPublishedProduct(productId));
     }
 
-    @ApiOperation("报价计算")
+    @ApiOperation(value = "报价计算",
+            notes = "内部服务间调用，供 hl-mp-service BFF 层 Feign 调用的报价计算接口。\n"
+                    + "计算逻辑与管理后台报价一致，根据日期和人数计算总价。")
     @PostMapping("/{productId}/quote")
     public Result<QuoteResultVO> calculateQuote(@PathVariable Long productId,
                                                @Valid @RequestBody QuoteRequest request) {
         return Result.success(quoteCalculatorService.calculateQuote(productId, request));
     }
 
-    @ApiOperation("产品线列表（活跃）")
+    @ApiOperation(value = "产品线列表（活跃）",
+            notes = "内部服务间调用，供 hl-mp-service 获取所有启用的产品线列表，用于小程序端筛选。")
     @GetMapping("/lines")
     public Result<List<ProductLineVO>> listActiveLines() {
         return Result.success(productLineService.listAllActive());
     }
 
-    @ApiOperation("推荐产品列表")
+    @ApiOperation(value = "推荐产品列表",
+            notes = "返回推荐的已上架产品。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，返回字段）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/recommend")
     public Result<List<MpProductListVO>> listRecommendProducts(
             @RequestParam(defaultValue = "6") int limit) {
         return Result.success(productService.listRecommendProducts(limit));
     }
 
-    @ApiOperation("C端价格日历")
+    @ApiOperation(value = "C端价格日历",
+            notes = "内部服务间调用，供 hl-mp-service 获取产品的价格日历数据。\n\n"
+                    + "可通过 startDate/endDate 限定查询范围，不传则返回今天及之后的所有可用日期。\n"
+                    + "返回每天的售价和库存信息，供小程序端日历选择器使用。")
     @GetMapping("/{productId}/price-calendar")
     public Result<List<Map<String, Object>>> getPriceCalendar(
             @PathVariable Long productId,
@@ -91,7 +108,10 @@ public class InternalMpProductController {
         return Result.success(priceCalendarService.getMpPriceCalendar(productId, startDate, endDate));
     }
 
-    @ApiOperation("产品最早可订日期")
+    @ApiOperation(value = "产品最早可订日期",
+            notes = "根据产品类型查询最早可预订日期。GROUP类型查批次出发日期，CORE/CUSTOM类型查价格日历。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，影响查询逻辑）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/earliest-booking-date")
     public Result<String> getEarliestBookingDate(@RequestParam Long productId) {
         Product product = productMapper.selectById(productId);
@@ -137,7 +157,10 @@ public class InternalMpProductController {
         }
     }
 
-    @ApiOperation("定制师产品统计（C端用）")
+    @ApiOperation(value = "定制师产品统计（C端用）",
+            notes = "统计指定定制师已发布的产品数量。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_status（产品状态，统计条件）：PUBLISHED=已上架")
     @GetMapping("/designer-stats")
     public Result<Map<String, Object>> getDesignerStats(@RequestParam Long customizerId) {
         long routeCount = productMapper.selectCount(

`hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java
index 978f513..7c0b2e7 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java
@@ -49,7 +49,7 @@ import java.util.stream.Collectors;
 @RestController
 @RequestMapping("/internal/product")
 @RequiredArgsConstructor
-@Api(tags = "【内部接口】产品（Feign调用）")
+@Api(tags = "【内部接口】产品（Feign调用）", hidden = true)
 public class InternalProductController {
 
     private final ProductStatusService productStatusService;
@@ -66,8 +66,12 @@ public class InternalProductController {
     private final GroupTourBatchMapper groupBatchMapper;
     private final ObjectMapper objectMapper;
 
+    @ApiOperation(value = "处理产品审批结果",
+            notes = "接收企微审批回调结果，更新产品状态。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_status（产品状态）：PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@Valid @RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@Valid @RequestBody ApprovalResultDTO dto) {
         try {
             productStatusService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
             return Result.success();
@@ -78,10 +82,12 @@ public class InternalProductController {
         }
     }
 
-    /**
-     * 获取产品详情（不过滤状态，供 order-service 创建订单时获取快照）
-     * 可选传入 date 参数，传入后会从资源价格日历查询各节点的成本价并填入快照
-     */
+    @ApiOperation(value = "获取产品详情（内部）",
+            notes = "不过滤状态，供 order-service 创建订单时获取快照。可选传入 date 参数查询各节点成本价。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @GetMapping("/{productId}/detail")
     public Result<ProductVO> getProductDetail(@PathVariable Long productId,
                                               @RequestParam(required = false) @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate date) {
@@ -91,19 +97,20 @@ public class InternalProductController {
         return Result.success(productService.getProduct(productId));
     }
 
-    /**
-     * 报价计算（供 order-service 创建订单时自动报价）
-     */
+    @ApiOperation(value = "报价计算（内部）",
+            notes = "供 order-service 创建订单时自动报价。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，影响计算逻辑）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PostMapping("/{productId}/quote")
     public Result<QuoteResultVO> calculateQuote(@PathVariable Long productId,
                                                @Valid @RequestBody QuoteRequest request) {
         return Result.success(quoteCalculatorService.calculateQuote(productId, request));
     }
 
-    /**
-     * 简单报价：直接从价格日历取售价 × 人数，不走资源价格计算。
-     * 小童 = 儿童售价 × 折扣比例，幼童 = 固定价格。
-     */
+    @ApiOperation(value = "简单报价（内部）",
+            notes = "直接从价格日历取售价乘以人数，不走资源价格计算。CUSTOM/ROUTE按整单，CORE/GROUP按人头。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，影响计算逻辑）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/{productId}/simple-quote")
     public Result<Map<String, Object>> simpleQuote(
             @PathVariable Long productId,
@@ -253,6 +260,10 @@ public class InternalProductController {
     /**
      * Deduct stock (optimistic lock: only succeeds if stock >= count)
      */
+    @ApiOperation(value = "扣减库存（内部）",
+            notes = "内部服务间调用，供 order-service 创建订单时扣减价格日历库存。\n\n"
+                    + "使用乐观锁机制：只有当库存 >= count 时才扣减成功。\n"
+                    + "扣减失败返回错误（库存不足），调用方需处理失败情况。")
     @PostMapping("/{productId}/deduct-stock")
     public Result<Void> deductStock(@PathVariable Long productId,
                                     @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") String date,
@@ -268,6 +279,9 @@ public class InternalProductController {
     /**
      * Restore stock (compensation for cancelled/expired orders)
      */
+    @ApiOperation(value = "恢复库存（内部）",
+            notes = "内部服务间调用，供 order-service 订单取消/过期时恢复价格日历库存。\n"
+                    + "用于补偿已扣减的库存，恢复数量不校验上限。")
     @PostMapping("/{productId}/restore-stock")
     public Result<Void> restoreStock(@PathVariable Long productId,
                                      @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") String date,
@@ -281,6 +295,9 @@ public class InternalProductController {
      * Get itinerary resources (SCENIC/ACTIVITY/HOTEL) for review service.
      * Returns deduplicated list of { resourceType, resourceId, resourceName }.
      */
+    @ApiOperation(value = "获取行程关联资源（内部）",
+            notes = "内部服务间调用，供 review-service 获取产品行程中关联的资源列表。\n\n"
+                    + "返回去重后的景区(SCENIC)、活动(ACTIVITY)、酒店(HOTEL)资源，用于评价时选择关联的资源对象。")
     @GetMapping("/{productId}/itinerary-resources")
     public Result<List<Map<String, Object>>> getItineraryResources(@PathVariable Long productId) {
         // Allowed resource types for review
@@ -310,9 +327,11 @@ public class InternalProductController {
         return Result.success(result);
     }
 
-    /**
-     * 变更定制产品状态（供 order-service 调用：下单→ORDERED / 取消→COMPLETED）
-     */
+    @ApiOperation(value = "变更定制产品状态（内部）",
+            notes = "供 order-service 调用：下单时 COMPLETED→ORDERED，取消时 ORDERED→COMPLETED。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，仅限CUSTOM）：CUSTOM=定制产品\n"
+                    + "- product_status（产品状态）：COMPLETED=已完成, ORDERED=已下单")
     @PutMapping("/{productId}/custom-status")
     public Result<Void> changeCustomProductStatus(@PathVariable Long productId,
                                                    @RequestParam String targetStatus) {
@@ -339,6 +358,10 @@ public class InternalProductController {
     /**
      * Enroll participants (optimistic lock on batch).
      */
+    @ApiOperation(value = "报名入团（内部）",
+            notes = "内部服务间调用，供 order-service 下单时增加批次已报名人数。\n\n"
+                    + "使用乐观锁机制：只有当剩余名额 >= peopleCount 时才报名成功。\n"
+                    + "报名成功后自动检查是否满员（FULL）或达到成团条件（CONFIRMED）。")
     @PostMapping("/batch/{batchId}/enroll")
     public Result<Void> enrollBatch(@PathVariable Long batchId,
                                      @RequestParam @Min(1) int peopleCount) {
@@ -349,6 +372,9 @@ public class InternalProductController {
     /**
      * Unenroll participants (compensation for cancellation).
      */
+    @ApiOperation(value = "退出报名（内部）",
+            notes = "内部服务间调用，供 order-service 订单取消/退款时减少批次已报名人数。\n"
+                    + "用于补偿已报名的人数，恢复剩余名额。")
     @PostMapping("/batch/{batchId}/unenroll")
     public Result<Void> unenrollBatch(@PathVariable Long batchId,
                                        @RequestParam @Min(1) int peopleCount) {
@@ -356,9 +382,10 @@ public class InternalProductController {
         return Result.success();
     }
 
-    /**
-     * Get batch info (for order snapshot).
-     */
+    @ApiOperation(value = "批次信息（内部）",
+            notes = "供 order-service 创建订单时获取批次快照。\n\n"
+                    + "**关联字典**：\n"
+                    + "- batch_status（批次状态，返回字段）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束")
     @GetMapping("/batch/{batchId}/info")
     public Result<Map<String, Object>> getBatchInfo(@PathVariable Long batchId) {
         GroupTourBatch batch = groupTourBatchService.getBatchById(batchId);
@@ -385,6 +412,10 @@ public class InternalProductController {
     /**
      * GROUP quote: returns adult/child dynamic pricing for a batch.
      */
+    @ApiOperation(value = "GROUP产品报价（内部）",
+            notes = "内部服务间调用，供 order-service 和 mp-service 获取 GROUP 产品按套餐组合的报价。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，仅限GROUP）：GROUP=小蒙马拼团")
     @GetMapping("/{productId}/group-quote")
     public Result<GroupQuoteResultVO> getGroupQuote(@PathVariable Long productId,
                                                      @RequestParam Long batchId,
@@ -395,6 +426,9 @@ public class InternalProductController {
     /**
      * C-end calendar data for GROUP products.
      */
+    @ApiOperation(value = "团期日历数据（内部）",
+            notes = "内部服务间调用，供小程序端展示 GROUP 产品的团期日历。\n\n"
+                    + "返回可报名批次的出发日期、状态、剩余名额等信息，用于日历选择器展示。")
     @GetMapping("/{productId}/batches/calendar")
     public Result<List<GroupBatchCalendarVO>> getBatchesCalendar(@PathVariable Long productId) {
         return Result.success(groupTourBatchService.listCalendar(productId));
@@ -403,6 +437,9 @@ public class InternalProductController {
     /**
      * C-end combo list for a batch (套餐列表).
      */
+    @ApiOperation(value = "批次套餐列表（内部）",
+            notes = "内部服务间调用，供小程序端展示 GROUP 产品批次下的套餐组合列表。\n\n"
+                    + "每个套餐包含成人/儿童人数搭配、售价、原价、库存和已售数量。")
     @GetMapping("/batch/{batchId}/combos")
     public Result<List<Map<String, Object>>> listBatchCombos(@PathVariable Long batchId) {
         List<GroupBatchCombo> combos = comboMapper.selectList(
@@ -431,7 +468,9 @@ public class InternalProductController {
 
     // ===== 定制师内部接口 =====
 
-    @ApiOperation("获取定制师已发布产品ID列表")
+    @ApiOperation(value = "获取定制师已发布产品ID列表",
+            notes = "**关联字典**：\n"
+                    + "- product_status（产品状态，筛选条件）：PUBLISHED=已上架")
     @GetMapping("/designer-published-ids")
     public Result<List<String>> getDesignerPublishedProductIds(@RequestParam Long createBy) {
         List<Long> ids = productService.getDesignerPublishedProductIds(createBy);
@@ -439,19 +478,28 @@ public class InternalProductController {
         return Result.success(strIds);
     }
 
-    @ApiOperation("获取全局产品统计")

`hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java
index f813a83..7ea5e3b 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java
@@ -28,7 +28,10 @@ public class ItineraryController {
 
     // ========================= Day =========================
 
-    @ApiOperation("更新行程天")
+    @ApiOperation(value = "更新行程天",
+            notes = "更新指定天的行程信息，如当天主题、概述等。\n"
+                    + "行程天在创建产品时根据 tripDays 自动生成，不支持单独增删，只能更新。\n"
+                    + "dayNumber 从 1 开始，对应第几天的行程。")
     @PutMapping("/item/{productId}/day/{dayNumber}")
     public Result<ItineraryDayVO> updateDay(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -37,7 +40,9 @@ public class ItineraryController {
         return Result.success(dayService.updateDay(productId, dayNumber, request));
     }
 
-    @ApiOperation("获取行程天列表")
+    @ApiOperation(value = "获取行程天列表",
+            notes = "获取产品所有行程天的信息，按 dayNumber 升序排列。\n"
+                    + "每一天包含当天主题、概述等信息，不包含节点详情（节点通过单独接口获取）。")
     @GetMapping("/item/{productId}/days")
     public Result<List<ItineraryDayVO>> listDays(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(dayService.listDays(productId));
@@ -45,7 +50,14 @@ public class ItineraryController {
 
     // ========================= Node =========================
 
-    @ApiOperation("添加行程节点")
+    @ApiOperation(value = "添加行程节点",
+            notes = "在指定天添加一个行程节点。节点是行程的最小单元，可关联资源服务中的景区、酒店、活动等。\n\n"
+                    + "**节点类型**：TRANSPORT(交通)/SCENIC(景区)/DINING(餐饮)/ACTIVITY(活动)/"
+                    + "PHOTOGRAPHY(摄影)/HOTEL(酒店)/FREE(自由活动)/CUSTOM(自定义)\n\n"
+                    + "**CUSTOM 定制产品特有**：可通过 familyIds 指定节点所属的家庭分组，实现按家庭分配行程。\n"
+                    + "新建节点自动追加到当天最后位置，可通过排序接口调整顺序。\n\n"
+                    + "**关联字典**：\n"
+                    + "- city（城市，资源面板筛选用）：用于在添加节点时按城市筛选可选资源")
     @PostMapping("/item/{productId}/day/{dayNumber}/node")
     public Result<ItineraryNodeVO> createNode(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -54,7 +66,12 @@ public class ItineraryController {
         return Result.success(nodeService.createNode(productId, dayNumber, request));
     }
 
-    @ApiOperation("更新行程节点")
+    @ApiOperation(value = "更新行程节点",
+            notes = "更新行程节点信息，仅传入需要修改的字段。\n"
+                    + "可修改节点名称、时间、关联资源、图片、描述等。\n\n"
+                    + "**关联字典**：\n"
+                    + "- city（城市）：资源面板城市筛选\n"
+                    + "- cities（城市ID映射）：城市名称预览")
     @PutMapping("/node/{nodeId}")
     public Result<ItineraryNodeVO> updateNode(
             @ApiParam("行程节点ID") @PathVariable Long nodeId,
@@ -62,14 +79,17 @@ public class ItineraryController {
         return Result.success(nodeService.updateNode(nodeId, request));
     }
 
-    @ApiOperation("删除行程节点")
+    @ApiOperation(value = "删除行程节点",
+            notes = "删除指定行程节点，同天其他节点的排序自动调整。")
     @DeleteMapping("/node/{nodeId}")
     public Result<Void> deleteNode(@ApiParam("行程节点ID") @PathVariable Long nodeId) {
         nodeService.deleteNode(nodeId);
         return Result.success();
     }
 
-    @ApiOperation("行程节点拖拽排序")
+    @ApiOperation(value = "行程节点拖拽排序",
+            notes = "重新排列指定天的所有行程节点顺序。前端拖拽排序后，将新的节点ID顺序全量提交。\n"
+                    + "nodeIds 列表中的顺序即为新的排序顺序（从上到下）。")
     @PutMapping("/item/{productId}/day/{dayNumber}/nodes/sort")
     public Result<Void> sortNodes(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -79,13 +99,17 @@ public class ItineraryController {
         return Result.success();
     }
 
-    @ApiOperation("复制行程节点")
+    @ApiOperation(value = "复制行程节点",
+            notes = "复制指定节点到同一天的末尾位置，包括节点的所有属性（名称、资源关联、图片等）。\n"
+                    + "适用场景：同一天有相似的行程安排时快速复制。")
     @PostMapping("/node/{nodeId}/copy")
     public Result<ItineraryNodeVO> copyNode(@ApiParam("行程节点ID") @PathVariable Long nodeId) {
         return Result.success(nodeService.copyNode(nodeId));
     }
 
-    @ApiOperation("移动行程节点到其他天")
+    @ApiOperation(value = "移动行程节点到其他天",
+            notes = "将节点从当前天移动到目标天的末尾位置。\n"
+                    + "移动后原天和目标天的节点排序自动调整。")
     @PutMapping("/node/{nodeId}/move")
     public Result<ItineraryNodeVO> moveNode(
             @ApiParam("行程节点ID") @PathVariable Long nodeId,
@@ -93,7 +117,12 @@ public class ItineraryController {
         return Result.success(nodeService.moveNode(nodeId, request.getTargetDayNumber()));
     }
 
-    @ApiOperation("获取某天的节点列表")
+    @ApiOperation(value = "获取某天的节点列表",
+            notes = "获取指定天的所有行程节点，按排序顺序返回。\n"
+                    + "每个节点包含类型、名称、时间、关联资源信息、图片等完整数据。\n\n"
+                    + "**关联字典**：\n"
+                    + "- city（城市）：资源面板城市筛选\n"
+                    + "- cities（城市ID映射）：城市名称预览")
     @GetMapping("/item/{productId}/day/{dayNumber}/nodes")
     public Result<List<ItineraryNodeVO>> listNodes(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -103,7 +132,10 @@ public class ItineraryController {
 
     // ========================= Hotel =========================
 
-    @ApiOperation("添加每日住宿")
+    @ApiOperation(value = "添加每日住宿",
+            notes = "为指定天添加住宿安排，关联资源服务中的酒店和房型。\n"
+                    + "每天可以有多个住宿选项（如不同档次），参与成本自动计算。\n"
+                    + "住宿费用会体现在价格日历的成本计算中。")
     @PostMapping("/item/{productId}/day/{dayNumber}/hotel")
     public Result<DayHotelVO> addHotel(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -112,7 +144,8 @@ public class ItineraryController {
         return Result.success(hotelService.addHotel(productId, dayNumber, request));
     }
 
-    @ApiOperation("更新每日住宿")
+    @ApiOperation(value = "更新每日住宿",
+            notes = "更新住宿记录的酒店、房型、数量等信息。")
     @PutMapping("/hotel/{id}")
     public Result<DayHotelVO> updateHotel(
             @ApiParam("住宿记录ID") @PathVariable Long id,
@@ -120,14 +153,16 @@ public class ItineraryController {
         return Result.success(hotelService.updateHotel(id, request));
     }
 
-    @ApiOperation("删除每日住宿")
+    @ApiOperation(value = "删除每日住宿",
+            notes = "删除指定住宿记录。删除后该天的住宿成本会从报价中移除。")
     @DeleteMapping("/hotel/{id}")
     public Result<Void> deleteHotel(@ApiParam("住宿记录ID") @PathVariable Long id) {
         hotelService.deleteHotel(id);
         return Result.success();
     }
 
-    @ApiOperation("获取某天的住宿列表")
+    @ApiOperation(value = "获取某天的住宿列表",
+            notes = "获取指定天的所有住宿安排，包含酒店名称、房型、数量等信息。")
     @GetMapping("/item/{productId}/day/{dayNumber}/hotels")
     public Result<List<DayHotelVO>> listHotels(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -137,7 +172,9 @@ public class ItineraryController {
 
     // ========================= Dining =========================
 
-    @ApiOperation("添加每日餐厅推荐")
+    @ApiOperation(value = "添加每日餐厅推荐",
+            notes = "为指定天添加餐饮推荐，关联资源服务中的餐厅。\n"
+                    + "用于展示当天的用餐安排，可按早/午/晚分类。")
     @PostMapping("/item/{productId}/day/{dayNumber}/dining")
     public Result<DiningOptionVO> addDiningOption(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -146,7 +183,8 @@ public class ItineraryController {
         return Result.success(diningOptionService.addDiningOption(productId, dayNumber, request));
     }
 
-    @ApiOperation("更新餐饮推荐")
+    @ApiOperation(value = "更新餐饮推荐",
+            notes = "更新餐饮推荐的餐厅、用餐类型（早/午/晚）、描述等信息。")
     @PutMapping("/dining/{id}")
     public Result<DiningOptionVO> updateDiningOption(
             @ApiParam("餐饮推荐ID") @PathVariable Long id,
@@ -154,7 +192,8 @@ public class ItineraryController {
         return Result.success(diningOptionService.updateDiningOption(id, request));
     }
 
-    @ApiOperation("获取某天的餐厅推荐列表")
+    @ApiOperation(value = "获取某天的餐厅推荐列表",
+            notes = "获取指定天的所有餐饮推荐，包含餐厅名称、用餐类型、描述等信息。")
     @GetMapping("/item/{productId}/day/{dayNumber}/dining")
     public Result<List<DiningOptionVO>> listDining(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -162,7 +201,8 @@ public class ItineraryController {
         return Result.success(diningOptionService.listDiningOptions(productId, dayNumber));
     }
 
-    @ApiOperation("删除餐饮推荐")
+    @ApiOperation(value = "删除餐饮推荐",
+            notes = "删除指定的餐饮推荐记录。")
     @DeleteMapping("/dining/{id}")
     public Result<Void> deleteDiningOption(@ApiParam("餐饮推荐ID") @PathVariable Long id) {
         diningOptionService.deleteDiningOption(id);
@@ -171,7 +211,9 @@ public class ItineraryController {
 
     // ========================= Supplies =========================
 
-    @ApiOperation("添加物资配品")
+    @ApiOperation(value = "添加物资配品",
+            notes = "为产品添加物资配品（如帐篷、睡袋、登山杖等），关联资源服务中的物资。\n"

`hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java
index 526bc16..94a6723 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java
@@ -31,19 +31,33 @@ public class MpProductController {
     private final ProductService productService;
     private final QuoteCalculatorService quoteCalculatorService;
 
-    @ApiOperation("产品列表")
+    @ApiOperation(value = "产品列表（C端）",
+            notes = "小程序端产品列表接口，仅返回已上架（PUBLISHED）的产品。\n\n"
+                    + "支持按产品类型、季节、行程天数、目的地、产品线、支付模式、定制师等筛选。\n"
+                    + "默认按 sortOrder 排序，也可按价格或行程天数排序。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，筛选条件）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @GetMapping("/list")
     public Result<PageResult<MpProductListVO>> listProducts(@ApiParam("产品查询请求") @Valid MpProductQueryRequest query) {
         return Result.success(productService.listPublishedProducts(query));
     }
 
-    @ApiOperation("产品详情")
+    @ApiOperation(value = "产品详情（C端）",
+            notes = "小程序端产品详情接口，仅返回已上架（PUBLISHED）的产品。\n"
+                    + "包含完整的行程信息、定价配置、费用说明、创作者寄语等。\n"
+                    + "未上架的产品会返回 404 错误。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @GetMapping("/{productId}")
     public Result<ProductVO> getProduct(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(productService.getPublishedProduct(productId));
     }
 
-    @ApiOperation("报价计算")
+    @ApiOperation(value = "报价计算（C端）",
+            notes = "小程序端报价计算接口，根据用户选择的日期和人数计算总价。\n"
+                    + "内部会校验产品是否存在且已上架。\n"
+                    + "详细计算逻辑参见管理后台的报价计算接口说明。")
     @PostMapping("/{productId}/quote")
     public Result<QuoteResultVO> calculateQuote(
             @ApiParam("产品ID") @PathVariable Long productId,

`hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java
index cdd0cb8..1599755 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java
@@ -28,7 +28,18 @@ public class PricingController {
 
     // ========== 定价规则 ==========
 
-    @ApiOperation("保存定价规则")
+    @ApiOperation(value = "保存定价规则",
+            notes = "保存或更新产品的定价配置（一个产品仅一条定价记录，重复调用为覆盖更新）。\n\n"
+                    + "**定价模式**：\n"
+                    + "- AUTO：自动计算，通过公式引擎根据行程资源价格自动测算成本和售价\n"
+                    + "- MANUAL：手动定价，直接在价格日历中手动设置每日价格\n"
+                    + "- CUSTOM：定制定价，设置整单总价（customTotalPrice），不按人头\n\n"
+                    + "**利润模式**（AUTO 模式下生效）：\n"
+                    + "- FIXED：固定金额加价，售价 = 成本 + profitAmount\n"
+                    + "- PERCENT：百分比加价，售价 = 成本 × (1 + markupPercent/100)\n\n"
+                    + "**支付方式**：FULL=全款支付，DEPOSIT=定金+尾款（需设置 depositRatio 或 depositAmount）\n\n"
+                    + "**关联字典**：\n"
+                    + "- vehicle_type（车型）：费用配置中车辆相关成本计算")
     @PostMapping("/pricing")
     public Result<ProductPricingVO> savePricing(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -36,7 +47,11 @@ public class PricingController {
         return Result.success(pricingService.savePricing(productId, request));
     }
 
-    @ApiOperation("获取定价规则")
+    @ApiOperation(value = "获取定价规则",
+            notes = "获取产品的定价配置，包括定价模式、利润设置、儿童/婴儿价格、支付方式等。\n"
+                    + "如果产品尚未设置定价规则，返回 null。\n\n"
+                    + "**关联字典**：\n"
+                    + "- vehicle_type（车型）：费用配置中车辆相关成本显示")
     @GetMapping("/pricing")
     public Result<ProductPricingVO> getPricing(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(pricingService.getPricing(productId));
@@ -44,7 +59,11 @@ public class PricingController {
 
     // ========== 价格日历 ==========
 
-    @ApiOperation("获取月度价格日历")
+    @ApiOperation(value = "获取月度价格日历",
+            notes = "获取指定月份的价格日历数据列表。\n\n"
+                    + "每条数据包含：日期、成人售价/成本价、儿童售价/成本价、库存、状态（OPEN/CLOSED）等。\n"
+                    + "**CORE/GROUP 产品**：价格为单人价格，按人头 × 价格计算总价。\n"
+                    + "**CUSTOM/ROUTE 产品**：价格为整单总价，不乘以人头数。")
     @GetMapping("/price-calendar")
     public Result<List<PriceCalendarVO>> getMonthCalendar(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -53,7 +72,10 @@ public class PricingController {
         return Result.success(calendarService.getMonthCalendar(productId, year, month));
     }
 
-    @ApiOperation("设置单日价格")
+    @ApiOperation(value = "设置单日价格",
+            notes = "设置或更新指定日期的价格和库存。如果该日期已有记录则更新，否则新建。\n\n"
+                    + "可设置成人售价/成本价、儿童售价/成本价、库存数量、状态（OPEN/CLOSED）。\n"
+                    + "状态为 CLOSED 的日期不会出现在小程序端的可选日期中。")
     @PostMapping("/price-calendar")
     public Result<PriceCalendarVO> setDayPrice(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -61,7 +83,11 @@ public class PricingController {
         return Result.success(calendarService.setDayPrice(productId, request));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格",
+            notes = "批量设置日期范围内的价格和库存，支持按星期筛选。\n\n"
+                    + "指定 startDate 和 endDate 日期范围，可选 selectedWeekdays 过滤星期几。\n"
+                    + "示例：设置5月1日-5月31日的工作日（周一到周五=[1,2,3,4,5]）价格。\n"
+                    + "selectedWeekdays 为空时，范围内所有日期都会被设置。")
     @PostMapping("/price-calendar/batch")
     public Result<List<PriceCalendarVO>> batchSetPrices(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -69,7 +95,13 @@ public class PricingController {
         return Result.success(calendarService.batchSetPrices(productId, request));
     }
 
-    @ApiOperation("测算预览（不写入数据库）")
+    @ApiOperation(value = "测算预览（不写入数据库）",
+            notes = "根据行程中的资源价格日历，自动计算指定日期的成本价和售价，仅预览不保存。\n\n"
+                    + "用于在设置价格日历前预览自动计算的结果。\n"
+                    + "计算逻辑：汇总当天所有行程节点关联资源的价格 → 应用公式引擎 → 加上利润。\n"
+                    + "GROUP 产品需要传 adultCount 参数（影响均摊计算）。\n\n"
+                    + "**关联字典**：\n"
+                    + "- vehicle_type（车型）：车辆费用成本测算")
     @PostMapping("/price-calendar/calc-preview")
     public Result<CalcPreviewVO> calcPreview(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -77,13 +109,21 @@ public class PricingController {
         return Result.success(calendarService.calcPreview(productId, request));
     }
 
-    @ApiOperation("重新测算所有自动测算日期的价格")
+    @ApiOperation(value = "重新测算所有自动测算日期的价格",
+            notes = "重新计算价格日历中所有 costAutoCalc=true 的日期的成本价和售价。\n\n"
+                    + "适用场景：资源价格调整后，批量刷新所有自动计算的价格日历。\n"
+                    + "返回更新的日期数量和详情。手动设置的价格（costAutoCalc=false）不受影响。")
     @PostMapping("/price-calendar/recalculate")
     public Result<java.util.Map<String, Object>> recalculate(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(calendarService.recalculateAll(productId));
     }
 
-    @ApiOperation("自动计算成本并同步到价格日历")
+    @ApiOperation(value = "自动计算成本并同步到价格日历",
+            notes = "根据出发日期和人数，自动计算成本并将结果写入价格日历。\n\n"
+                    + "与测算预览不同，此接口会实际更新价格日历数据。\n"
+                    + "计算逻辑：查询各资源的价格日历 → 汇总成本 → 应用公式和利润规则 → 写入结果。\n\n"
+                    + "**关联字典**：\n"
+                    + "- vehicle_type（车型）：车辆费用成本计算")
     @PostMapping("/price-calendar/auto-calc")
     public Result<QuoteResultVO> autoCalcCost(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -100,7 +140,10 @@ public class PricingController {
 
     // ========== 费用包含/不包含 ==========
 
-    @ApiOperation("添加费用项")
+    @ApiOperation(value = "添加费用项",
+            notes = "添加产品的费用包含/不包含说明项。\n\n"
+                    + "用于在产品详情页展示\"费用包含\"和\"费用不包含\"信息。\n"
+                    + "仅用于前端展示，不参与报价计算。")
     @PostMapping("/cost-item")
     public Result<ProductCostItemVO> addCostItem(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -108,7 +151,8 @@ public class PricingController {
         return Result.success(costItemService.addCostItem(productId, request));
     }
 
-    @ApiOperation("更新费用项")
+    @ApiOperation(value = "更新费用项",
+            notes = "更新费用包含/不包含说明项的内容。仅用于前端展示，不参与报价计算。")
     @PutMapping("/cost-item/{itemId}")
     public Result<ProductCostItemVO> updateCostItem(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -117,7 +161,8 @@ public class PricingController {
         return Result.success(costItemService.updateCostItem(itemId, request));
     }
 
-    @ApiOperation("删除费用项")
+    @ApiOperation(value = "删除费用项",
+            notes = "删除费用包含/不包含说明项。")
     @DeleteMapping("/cost-item/{itemId}")
     public Result<Void> deleteCostItem(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -126,7 +171,8 @@ public class PricingController {
         return Result.success();
     }
 
-    @ApiOperation("获取费用项列表")
+    @ApiOperation(value = "获取费用项列表",
+            notes = "获取产品的所有费用包含/不包含说明项列表。")
     @GetMapping("/cost-items")
     public Result<List<ProductCostItemVO>> listCostItems(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(costItemService.listCostItems(productId));
@@ -134,7 +180,10 @@ public class PricingController {
 
     // ========== 额外成本关联 ==========
 
-    @ApiOperation("添加额外成本关联")
+    @ApiOperation(value = "添加额外成本关联",
+            notes = "关联资源服务中的费用项（cost_item）到产品，参与成本自动计算。\n\n"
+                    + "额外成本是指不包含在行程节点中、但需要计入总成本的费用。\n"
+                    + "例如：导游服务费、保险费、通讯费等固定运营开支。")
     @PostMapping("/extra-cost")
     public Result<ProductExtraCostVO> addExtraCost(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -142,7 +191,8 @@ public class PricingController {
         return Result.success(extraCostService.addExtraCost(productId, request));
     }
 
-    @ApiOperation("更新额外成本关联")
+    @ApiOperation(value = "更新额外成本关联",
+            notes = "更新额外成本关联的费用项、数量等信息。修改后会影响成本自动计算结果。")
     @PutMapping("/extra-cost/{ecId}")
     public Result<ProductExtraCostVO> updateExtraCost(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -151,7 +201,8 @@ public class PricingController {
         return Result.success(extraCostService.updateExtraCost(ecId, request));
     }
 
-    @ApiOperation("删除额外成本关联")
+    @ApiOperation(value = "删除额外成本关联",
+            notes = "删除额外成本关联记录。删除后该费用项不再计入成本自动计算。")
     @DeleteMapping("/extra-cost/{ecId}")
     public Result<Void> removeExtraCost(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -160,7 +211,8 @@ public class PricingController {
         return Result.success();
     }
 
-    @ApiOperation("获取额外成本关联列表")
+    @ApiOperation(value = "获取额外成本关联列表",
+            notes = "获取产品关联的所有额外成本项列表，包含费用项名称、金额等信息。")
     @GetMapping("/extra-costs")
     public Result<List<ProductExtraCostVO>> listExtraCosts(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(extraCostService.listExtraCosts(productId));
@@ -168,7 +220,10 @@ public class PricingController {

`hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java
index bc250d7..5f48dff 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java
@@ -28,7 +28,20 @@ public class ProductController {
     private final ProductStatusService productStatusService;
     private final RouteMapService routeMapService;
 
-    @ApiOperation("创建产品（草稿）")
+    @ApiOperation(value = "创建产品（草稿）",
+            notes = "创建一个新产品，初始状态为 DRAFT（草稿）。\n\n"
+                    + "**产品类型说明**：\n"
+                    + "- CORE：核心产品，标准旅游产品，支持上架/下架审批流程\n"
+                    + "- GROUP：小蒙马拼团，需配合团期批次管理，按人头计价\n"
+                    + "- CUSTOM：定制产品，由定制师为客户量身定制，按单计价\n"
+                    + "- ROUTE：线路产品，预设线路模板，按单计价\n\n"
+                    + "**注意事项**：\n"
+                    + "- 创建后需依次完善行程、定价、价格日历等信息\n"
+                    + "- CUSTOM/ROUTE 产品的价格日历存储的是整单总价，不按人头乘算\n"
+                    + "- GROUP 产品需额外创建团期批次才能报名\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @PostMapping
     public Result<ProductVO> createProduct(
             @ApiParam("创建产品请求") @Valid @RequestBody ProductCreateRequest request,
@@ -37,13 +50,28 @@ public class ProductController {
         return Result.success(productService.createProduct(request, adminId));
     }
 
-    @ApiOperation("获取产品详情")
+    @ApiOperation(value = "获取产品详情",
+            notes = "获取产品完整信息，包括基本信息、行程天列表、定价配置、费用项等。\n"
+                    + "返回数据包含关联的行程节点资源详情，适用于产品编辑页面。\n"
+                    + "不过滤产品状态，所有状态的产品都可查看。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @GetMapping("/{productId}")
     public Result<ProductVO> getProduct(@ApiParam("产品ID") @PathVariable Long productId) {
         return Result.success(productService.getProduct(productId));
     }
 
-    @ApiOperation("更新产品")
+    @ApiOperation(value = "更新产品",
+            notes = "更新产品基本信息，仅传入需要修改的字段，未传字段不会被覆盖。\n\n"
+                    + "**权限说明**：\n"
+                    + "- 普通管理员只能编辑自己创建的产品\n"
+                    + "- SUPER_ADMIN 可编辑所有产品\n\n"
+                    + "**注意**：行程、定价、价格日历等通过各自独立的接口管理，不在此接口中处理。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾")
     @PutMapping("/{productId}")
     public Result<ProductVO> updateProduct(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -54,7 +82,10 @@ public class ProductController {
         return Result.success(productService.updateProduct(productId, request, adminId, role));
     }
 
-    @ApiOperation("删除产品")
+    @ApiOperation(value = "删除产品",
+            notes = "软删除产品（设置 deleted_at 字段）。\n\n"
+                    + "**权限说明**：普通管理员只能删除自己创建的产品，SUPER_ADMIN 可删除所有产品。\n"
+                    + "**限制**：已上架（PUBLISHED）的产品不能直接删除，需先下架。")
     @DeleteMapping("/{productId}")
     public Result<Void> deleteProduct(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -65,17 +96,33 @@ public class ProductController {
         return Result.success();
     }
 
-    @ApiOperation("产品列表")
+    @ApiOperation(value = "产品列表",
+            notes = "分页查询产品列表，支持多维度筛选和排序。\n\n"
+                    + "**权限说明**：\n"
+                    + "- 普通管理员只能看到自己创建的产品\n"
+                    + "- SUPER_ADMIN 可看到所有产品\n\n"
+                    + "**筛选条件**：关键词（名称/副标题模糊匹配）、产品类型、状态、文件夹、产品线、季节、行程天数。\n"
+                    + "支持多状态筛选（statuses 字段，逗号分隔）。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，筛选条件）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态，筛选条件+返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单")
     @GetMapping("/list")
     public Result<PageResult<ProductListVO>> listProducts(
             @ApiParam("产品查询请求") @Valid ProductQueryRequest query,
             HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);
-        boolean isSuperAdmin = "SUPER_ADMIN".equals(httpRequest.getAttribute("role"));
-        return Result.success(productService.listProducts(query, adminId, isSuperAdmin));
+        String role = (String) httpRequest.getAttribute("role");
+        boolean canViewAll = "SUPER_ADMIN".equals(role) || "CUSTOMER_SERVICE".equals(role);
+        return Result.success(productService.listProducts(query, adminId, canViewAll));
     }
 
-    @ApiOperation("复制产品")
+    @ApiOperation(value = "复制产品",
+            notes = "深度复制产品，包括行程天、行程节点、定价配置、住宿、餐饮、物资、人员配置等所有关联数据。\n\n"
+                    + "复制后的产品状态为 DRAFT，名称自动添加\"(副本)\"后缀。\n"
+                    + "适用场景：基于已有产品快速创建新产品。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，返回字段）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态，复制后固定为 DRAFT）")
     @PostMapping("/{productId}/copy")
     public Result<ProductVO> copyProduct(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -84,7 +131,9 @@ public class ProductController {
         return Result.success(productService.copyProduct(productId, adminId));
     }
 
-    @ApiOperation("移动产品到文件夹")
+    @ApiOperation(value = "移动产品到文件夹",
+            notes = "将产品移动到指定文件夹，或移出文件夹（folderId 传空字符串或 null）。\n"
+                    + "文件夹用于组织管理产品，不影响产品的业务逻辑。")
     @PutMapping("/{productId}/move")
     public Result<Void> moveProduct(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -95,7 +144,10 @@ public class ProductController {
         return Result.success();
     }
 
-    @ApiOperation("生成定制产品分享链接")
+    @ApiOperation(value = "生成定制产品分享链接",
+            notes = "为 CUSTOM（定制）产品生成小程序分享链接，用于定制师发送给客户查看方案。\n\n"
+                    + "**限制**：仅 CUSTOM 类型且状态为 COMPLETED 的产品可生成。\n"
+                    + "**权限**：普通管理员只能为自己创建的产品生成链接，SUPER_ADMIN 不受限制。")
     @PostMapping("/{productId}/share-link")
     public Result<ShareLinkVO> generateShareLink(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -105,7 +157,10 @@ public class ProductController {
         return Result.success(productService.generateShareLink(productId, adminId, role));
     }
 
-    @ApiOperation("手动生成路径图")
+    @ApiOperation(value = "手动生成路径图",
+            notes = "根据产品行程节点的经纬度信息，调用地图API生成行程路径图。\n\n"
+                    + "通常在行程编辑完成后手动触发，生成结果为 OSS 图片 URL。\n"
+                    + "如果行程节点没有经纬度信息，则无法生成路径图。")
     @PostMapping("/{productId}/generate-route-map")
     public Result<String> generateRouteMap(@ApiParam("产品ID") @PathVariable Long productId) {
         try {
@@ -116,7 +171,20 @@ public class ProductController {
         }
     }
 
-    @ApiOperation("产品状态变更（上架/下架等）")
+    @ApiOperation(value = "产品状态变更（上架/下架/完成）",
+            notes = "根据产品类型，状态流转规则不同：\n\n"
+                    + "**核心产品(CORE) / 小蒙马(GROUP)**：支持上架/下架，需企微审批\n"
+                    + "- DRAFT → PENDING_REVIEW → REVIEWED → PUBLISHED（上架）\n"
+                    + "- PUBLISHED → UNPUBLISHED（下架）\n"
+                    + "- UNPUBLISHED → PUBLISHED（重新上架）\n"
+                    + "- REJECTED → DRAFT（驳回后重新编辑）\n\n"
+                    + "**定制产品(CUSTOM)**：仅支持完成，无上架/下架概念\n"
+                    + "- DRAFT → COMPLETED（定制师完成设计）\n"
+                    + "- COMPLETED → ORDERED（客户下单，系统自动变更）\n"
+                    + "- ORDERED → COMPLETED（订单取消/退款后回退）\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，影响状态流转规则）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品\n"
+                    + "- product_status（产品状态，请求+返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单")
     @PutMapping("/{productId}/status")
     public Result<Void> changeStatus(
             @ApiParam("产品ID") @PathVariable Long productId,

`hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java
index 2562b23..2b69413 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductFolderController.java
@@ -23,7 +23,9 @@ public class ProductFolderController {
 
     private final ProductFolderService folderService;
 
-    @ApiOperation("创建文件夹")
+    @ApiOperation(value = "创建文件夹",
+            notes = "创建产品文件夹，用于组织管理产品。支持多级目录结构。\n"
+                    + "文件夹归属于创建人，普通管理员只能看到自己的文件夹。")
     @PostMapping
     public Result<ProductFolderVO> createFolder(
             @ApiParam("创建文件夹请求") @Valid @RequestBody FolderCreateRequest request,
@@ -33,7 +35,9 @@ public class ProductFolderController {
         return Result.success(folderService.createFolder(request, adminId, ownerName));
     }
 
-    @ApiOperation("更新文件夹")
+    @ApiOperation(value = "更新文件夹",
+            notes = "更新文件夹名称等信息。\n"
+                    + "**权限说明**：普通管理员只能更新自己创建的文件夹，SUPER_ADMIN 可更新任何文件夹。")
     @PutMapping("/{folderId}")
     public Result<ProductFolderVO> updateFolder(
             @ApiParam("文件夹ID") @PathVariable Long folderId,
@@ -44,7 +48,9 @@ public class ProductFolderController {
         return Result.success(folderService.updateFolder(folderId, request, adminId, isSuperAdmin));
     }
 
-    @ApiOperation("删除文件夹")
+    @ApiOperation(value = "删除文件夹",
+            notes = "删除文件夹。如果文件夹下有产品，产品会自动移到根目录（folderId 置空）。\n"
+                    + "普通管理员只能删除自己的文件夹，SUPER_ADMIN 可删除任何文件夹。")
     @DeleteMapping("/{folderId}")
     public Result<Void> deleteFolder(@ApiParam("文件夹ID") @PathVariable Long folderId, HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);
@@ -53,7 +59,10 @@ public class ProductFolderController {
         return Result.success();
     }
 
-    @ApiOperation("获取文件夹树")
+    @ApiOperation(value = "获取文件夹树",
+            notes = "获取当前用户可见的文件夹树形结构。\n"
+                    + "普通管理员只能看到自己创建的文件夹，SUPER_ADMIN 可看到所有文件夹。\n"
+                    + "返回结构为嵌套的树形列表，包含每个文件夹的子文件夹。")
     @GetMapping("/tree")
     public Result<List<ProductFolderVO>> getFolderTree(HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);

`hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java
index 28d7d17..13683ab 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java
@@ -25,7 +25,9 @@ public class ProductLineController {
 
     private final ProductLineService lineService;
 
-    @ApiOperation("创建产品线")
+    @ApiOperation(value = "创建产品线",
+            notes = "创建产品线，用于对产品进行业务分类（如：亲子游、蜜月游、探险游等）。\n"
+                    + "产品线在小程序端可作为筛选条件，帮助用户快速找到感兴趣的产品类别。")
     @PostMapping
     public Result<ProductLineVO> createLine(
             @ApiParam("创建产品线请求") @Valid @RequestBody LineCreateRequest request,
@@ -34,7 +36,8 @@ public class ProductLineController {
         return Result.success(lineService.createLine(request, adminId));
     }
 
-    @ApiOperation("更新产品线")
+    @ApiOperation(value = "更新产品线",
+            notes = "更新产品线名称、描述、状态等信息。")
     @PutMapping("/{lineId}")
     public Result<ProductLineVO> updateLine(
             @ApiParam("产品线ID") @PathVariable Long lineId,
@@ -42,26 +45,31 @@ public class ProductLineController {
         return Result.success(lineService.updateLine(lineId, request));
     }
 
-    @ApiOperation("删除产品线")
+    @ApiOperation(value = "删除产品线",
+            notes = "删除产品线（软删除）。已关联产品的产品线仍可删除，但关联产品的产品线字段不会被清空。")
     @DeleteMapping("/{lineId}")
     public Result<Void> deleteLine(@ApiParam("产品线ID") @PathVariable Long lineId) {
         lineService.deleteLine(lineId);
         return Result.success();
     }
 
-    @ApiOperation("产品线详情")
+    @ApiOperation(value = "产品线详情",
+            notes = "获取指定产品线的完整信息。")
     @GetMapping("/{lineId}")
     public Result<ProductLineVO> getLine(@ApiParam("产品线ID") @PathVariable Long lineId) {
         return Result.success(lineService.getLine(lineId));
     }
 
-    @ApiOperation("产品线列表（分页）")
+    @ApiOperation(value = "产品线列表（分页）",
+            notes = "分页查询产品线列表，支持按名称关键词筛选。")
     @GetMapping("/list")
     public Result<PageResult<ProductLineVO>> listLines(@ApiParam("产品线查询请求") @Valid LineQueryRequest query) {
         return Result.success(lineService.listLines(query));
     }
 
-    @ApiOperation("所有启用的产品线")
+    @ApiOperation(value = "所有启用的产品线",
+            notes = "获取所有启用状态的产品线，不分页。\n"
+                    + "适用于产品编辑时的产品线下拉选择，以及小程序端的筛选项。")
     @GetMapping("/active")
     public Result<List<ProductLineVO>> listAllActive() {
         return Result.success(lineService.listAllActive());

`hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java b/hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java
index b6676e4..81f33f0 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java
@@ -23,7 +23,18 @@ public class QuoteController {
     private final QuoteCalculatorService quoteCalculatorService;
     private final CostCalculationService costCalculationService;
 
-    @ApiOperation("计算报价")
+    @ApiOperation(value = "计算报价",
+            notes = "根据出发日期和人数组合，计算产品的完整报价。\n\n"
+                    + "**计算流程**：\n"
+                    + "1. 从价格日历获取指定日期的单价\n"
+                    + "2. 按人数类型分别计算：成人 × 成人价、儿童 × 儿童价\n"
+                    + "3. 小童按儿童价 × 折扣比例（childDiscountPercent）计算\n"
+                    + "4. 婴儿使用固定价格（babyPrice）\n"
+                    + "5. 儿童加床（childNeedBed=true）额外加收 childWithBed 费用\n\n"
+                    + "**CUSTOM/ROUTE 产品**：价格日历存的是整单总价，不按人头乘算。\n"
+                    + "**GROUP 产品**：建议使用 group-quote 接口，支持套餐组合报价。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，影响计算逻辑）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品")
     @PostMapping("/quote")
     public Result<QuoteResultVO> calculateQuote(
             @ApiParam("产品ID") @PathVariable Long productId,
@@ -31,7 +42,13 @@ public class QuoteController {
         return Result.success(quoteCalculatorService.calculateQuote(productId, request));
     }
 
-    @ApiOperation("GROUP产品报价（按组合）")
+    @ApiOperation(value = "GROUP产品报价（按套餐组合）",
+            notes = "为 GROUP（小蒙马拼团）产品按团期批次和套餐组合计算报价。\n\n"
+                    + "GROUP 产品的价格由批次下的套餐组合（combo）决定，不同组合有不同的成人/儿童人数搭配和价格。\n"
+                    + "传入 batchId 指定团期批次，adultCount 用于匹配合适的套餐组合。\n\n"
+                    + "**与普通报价的区别**：普通报价从价格日历取单价，GROUP 报价从套餐组合取打包价。\n\n"
+                    + "**关联字典**：\n"
+                    + "- product_type（产品类型，仅限GROUP）：GROUP=小蒙马拼团")
     @GetMapping("/group-quote")
     public Result<GroupQuoteResultVO> calculateGroupQuote(
             @ApiParam("产品ID") @PathVariable Long productId,

`hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java
index 223810b..84591cf 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java
@@ -9,7 +9,7 @@ import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.Size;
 
 @Data
-@ApiModel("家庭分组保存请求")
+@ApiModel(value = "家庭分组保存请求", description = "仅适用于CUSTOM定制产品，用于将行程按家庭单位分配")
 public class FamilySaveRequest {
 
     @ApiModelProperty(value = "家庭名称", required = true, example = "家庭1")

`hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java
index 4acb045..89b3240 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java
@@ -29,7 +29,8 @@ public class FormulaStepRequest {
     @ApiModelProperty(value = "执行顺序", example = "1")
     private Integer executionOrder;
 
-    @ApiModelProperty(value = "表达式", required = true, example = "baseCost = adultCount * adultUnitCost + childCount * childUnitCost")
+    @ApiModelProperty(value = "Aviator表达式（支持数学运算、条件判断、内置函数；可引用前置步骤的输出变量和公式变量表中的变量）",
+            required = true, example = "baseCost = adultCount * adultUnitCost + childCount * childUnitCost")
     @NotBlank(message = "表达式不能为空")
     @Size(max = 2000, message = "表达式不能超过2000个字符")
     private String expression;

`hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java
index 70e06ec..2cf6432 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java
@@ -8,34 +8,34 @@ import javax.validation.constraints.*;
 import java.time.LocalDate;
 
 @Data
-@ApiModel("create group batch request")
+@ApiModel("创建拼团批次请求")
 public class GroupBatchCreateRequest {
 
-    @ApiModelProperty(value = "batch name", required = true, example = "Jul 20 Batch 1")
-    @NotBlank(message = "batch name required")
+    @ApiModelProperty(value = "批次名称", required = true, example = "7月20日第1批")
+    @NotBlank(message = "批次名称不能为空")
     @Size(max = 128)
     private String batchName;
 
-    @ApiModelProperty(value = "departure date", required = true, example = "2026-07-20")
-    @NotNull(message = "departure date required")
+    @ApiModelProperty(value = "出发日期", required = true, example = "2026-07-20")
+    @NotNull(message = "出发日期不能为空")
     private LocalDate departureDate;
 
-    @ApiModelProperty(value = "enrollment deadline", required = true, example = "2026-07-15")
-    @NotNull(message = "enrollment deadline required")
+    @ApiModelProperty(value = "报名截止日期，必须早于出发日期", required = true, example = "2026-07-15")
+    @NotNull(message = "报名截止日期不能为空")
     private LocalDate enrollmentDeadline;
 
-    @ApiModelProperty(value = "min participants for group confirmation (0=no limit)", example = "10")
+    @ApiModelProperty(value = "最低成团人数（0=不限制，达到此人数自动变为CONFIRMED状态）", example = "10")
     @Min(0)
     private int minParticipants = 0;
 
-    @ApiModelProperty(value = "max participants", required = true, example = "30")
-    @Min(value = 1, message = "max participants must be >= 1")
+    @ApiModelProperty(value = "最大参团人数（报名人数达到上限后自动关闭报名）", required = true, example = "30")
+    @Min(value = 1, message = "最大参团人数至少为1")
     private int maxParticipants;
 
-    @ApiModelProperty(value = "remark", example = "summer special batch")
+    @ApiModelProperty(value = "备注说明", example = "暑期特别批次")
     @Size(max = 512)
     private String remark;
 
-    @ApiModelProperty(value = "sort order", example = "0")
+    @ApiModelProperty(value = "排序序号（越小越靠前）", example = "0")
     private int sortOrder = 0;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java
index 369a7ca..ca769e4 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchDisbandRequest.java
@@ -8,11 +8,11 @@ import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.Size;
 
 @Data
-@ApiModel("disband batch request")
+@ApiModel("解散批次请求")
 public class GroupBatchDisbandRequest {
 
-    @ApiModelProperty(value = "disband reason", required = true, example = "insufficient enrollment")
-    @NotBlank(message = "disband reason required")
+    @ApiModelProperty(value = "解散原因（如：报名人数不足、行程调整等）", required = true, example = "报名人数不足")
+    @NotBlank(message = "解散原因不能为空")
     @Size(max = 512)
     private String reason;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java
index 8c2f4bb..712181e 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchStaffRequest.java
@@ -9,22 +9,22 @@ import javax.validation.constraints.NotNull;
 import javax.validation.constraints.Size;
 
 @Data
-@ApiModel("batch staff assignment request")
+@ApiModel("批次服务人员分配请求")
 public class GroupBatchStaffRequest {
 
-    @ApiModelProperty(value = "staff ID (from resource-service)", required = true, example = "1760000000000001")
-    @NotNull(message = "staff ID required")
+    @ApiModelProperty(value = "人员ID（来自资源服务的人员库）", required = true, example = "1760000000000001")
+    @NotNull(message = "人员ID不能为空")
     private Long staffId;
 
-    @ApiModelProperty(value = "role in this batch: LEADER/PHOTOGRAPHER/DRIVER/OTHER", required = true, example = "LEADER")
-    @NotBlank(message = "staff role required")
+    @ApiModelProperty(value = "在该批次中的角色：LEADER(领队)/PHOTOGRAPHER(摄影师)/DRIVER(司机)/OTHER(其他)", required = true, example = "LEADER")
+    @NotBlank(message = "人员角色不能为空")
     @Size(max = 32)
     private String staffRole;
 
-    @ApiModelProperty(value = "remark", example = "main guide")
+    @ApiModelProperty(value = "备注（如：主导游、备用摄影师等）", example = "主导游")
     @Size(max = 256)
     private String remark;
 
-    @ApiModelProperty(value = "sort order", example = "0")
+    @ApiModelProperty(value = "排序序号（越小越靠前）", example = "0")
     private int sortOrder = 0;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java
index a8e2de6..4532f60 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java
@@ -9,31 +9,31 @@ import javax.validation.constraints.Size;
 import java.time.LocalDate;
 
 @Data
-@ApiModel("update group batch request")
+@ApiModel("更新拼团批次请求")
 public class GroupBatchUpdateRequest {
 
-    @ApiModelProperty(value = "batch name", example = "Jul 20 Batch 1")
+    @ApiModelProperty(value = "批次名称", example = "7月20日第1批")
     @Size(max = 128)
     private String batchName;
 
-    @ApiModelProperty(value = "departure date", example = "2026-07-20")
+    @ApiModelProperty(value = "出发日期", example = "2026-07-20")
     private LocalDate departureDate;
 
-    @ApiModelProperty(value = "enrollment deadline", example = "2026-07-15")
+    @ApiModelProperty(value = "报名截止日期", example = "2026-07-15")
     private LocalDate enrollmentDeadline;
 
-    @ApiModelProperty(value = "min participants", example = "10")
+    @ApiModelProperty(value = "最低成团人数（0=不限制）", example = "10")
     @Min(0)
     private Integer minParticipants;
 
-    @ApiModelProperty(value = "max participants", example = "30")
+    @ApiModelProperty(value = "最大参团人数（不能低于已报名人数）", example = "30")
     @Min(1)
     private Integer maxParticipants;
 
-    @ApiModelProperty(value = "remark")
+    @ApiModelProperty(value = "备注说明")
     @Size(max = 512)
     private String remark;
 
-    @ApiModelProperty(value = "sort order")
+    @ApiModelProperty(value = "排序序号")
     private Integer sortOrder;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java
index a19ae8a..eae3469 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java
@@ -37,10 +37,10 @@ public class NodeCreateRequest {
     @ApiModelProperty(value = "纬度", example = "26.872108")
     private BigDecimal latitude;
 
-    @ApiModelProperty(value = "关联资源类型：SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE", example = "SCENIC_SPOT")
+    @ApiModelProperty(value = "关联资源类型（关联后可从资源服务获取价格参与成本计算）：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE", example = "SCENIC")
     private String resourceType;
 
-    @ApiModelProperty(value = "关联资源ID", example = "1893012345678901234")
+    @ApiModelProperty(value = "关联资源ID（来自资源服务，关联后节点名称和图片可自动同步）", example = "1893012345678901234")
     private String resourceId;
 
     @ApiModelProperty(value = "节点描述", example = "漫步古城，感受纳西文化")
@@ -58,6 +58,6 @@ public class NodeCreateRequest {
     @ApiModelProperty(value = "数量", example = "1")
     private Integer quantity;
 
-    @ApiModelProperty(value = "所属家庭ID列表（定制产品按家庭分配）")
+    @ApiModelProperty(value = "所属家庭ID列表（仅CUSTOM定制产品使用，实现按家庭分配行程节点）")
     private List<String> familyIds;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java
index a5188da..dacb69c 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java
@@ -28,13 +28,13 @@ public class PriceCalendarRequest {
     @ApiModelProperty(value = "儿童成本价", example = "1800.00")
     private BigDecimal childCostPrice;
 
-    @ApiModelProperty(value = "是否自动计算成本", example = "true")
+    @ApiModelProperty(value = "是否自动计算成本（true时重新测算会自动更新此日期的价格）", example = "true")
     private Boolean costAutoCalc;
 
-    @ApiModelProperty(value = "库存数量", example = "30")
+    @ApiModelProperty(value = "库存数量（CORE/GROUP按人头扣减，CUSTOM/ROUTE按单扣减）", example = "30")
     private Integer stock;
 
-    @ApiModelProperty(value = "状态：OPEN=开放 CLOSED=关闭", example = "OPEN")
+    @ApiModelProperty(value = "状态：OPEN=开放预订 CLOSED=关闭（不可预订）", example = "OPEN")
     private String status;
 
     @ApiModelProperty(value = "备注", example = "五一黄金周特价")

`hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java
index 28b7e49..a937367 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java
@@ -11,10 +11,10 @@ import java.util.List;
 @ApiModel("定价配置请求")
 public class PricingRequest {
 
-    @ApiModelProperty(value = "定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价", example = "AUTO")
+    @ApiModelProperty(value = "定价模式：AUTO=根据行程资源价格自动计算 MANUAL=手动在价格日历设置每日价格 CUSTOM=定制产品整单定价", example = "AUTO")
     private String pricingMode;
 
-    @ApiModelProperty(value = "利润模式：FIXED=固定金额 PERCENT=百分比", example = "FIXED")
+    @ApiModelProperty(value = "利润模式（AUTO模式下生效）：FIXED=在成本基础上加固定金额 PERCENT=在成本基础上按百分比加价", example = "FIXED")
     private String profitMode;
 
     @ApiModelProperty(value = "利润金额（FIXED模式下使用）", example = "500.00")
@@ -32,16 +32,16 @@ public class PricingRequest {
     @ApiModelProperty(value = "餐费预算", example = "100.00")
     private BigDecimal mealBudget;
 
-    @ApiModelProperty(value = "儿童占床价", example = "1800.00")
+    @ApiModelProperty(value = "儿童加床费（childNeedBed=true时额外加收的费用）", example = "1800.00")
     private BigDecimal childWithBed;
 
-    @ApiModelProperty(value = "儿童不占床价", example = "1200.00")
+    @ApiModelProperty(value = "儿童不占床价（暂未使用，预留字段）", example = "1200.00")
     private BigDecimal childNoBed;
 
-    @ApiModelProperty(value = "婴儿价", example = "300.00")
+    @ApiModelProperty(value = "婴儿固定价格（不随日期变化）", example = "300.00")
     private BigDecimal babyPrice;
 
-    @ApiModelProperty(value = "儿童折扣百分比", example = "70.00")
+    @ApiModelProperty(value = "小童折扣百分比（小童价=儿童价×此百分比/100，如70表示打7折）", example = "70.00")
     private BigDecimal childDiscountPercent;
 
     @ApiModelProperty(value = "车型ID列表")
@@ -56,24 +56,24 @@ public class PricingRequest {
     @ApiModelProperty(value = "陪同人员价格", example = "0.00")
     private BigDecimal companionPrice;
 
-    @ApiModelProperty(value = "定制产品总价（CUSTOM模式下使用）", example = "28800.00")
+    @ApiModelProperty(value = "定制产品总价（CUSTOM定价模式下使用，代表整单总价）", example = "28800.00")
     private BigDecimal customTotalPrice;
 
-    @ApiModelProperty(value = "最小成团人数", example = "2")
+    @ApiModelProperty(value = "最小成团人数（CORE/GROUP产品用，影响均摊成本计算）", example = "2")
     private Integer minGroupSize;
 
-    @ApiModelProperty(value = "最大成团人数", example = "16")
+    @ApiModelProperty(value = "最大成团人数（CORE/GROUP产品用）", example = "16")
     private Integer maxGroupSize;
 
-    @ApiModelProperty(value = "支付方式：FULL=全款 DEPOSIT=定金+尾款", example = "FULL")
+    @ApiModelProperty(value = "支付方式：FULL=全款支付 DEPOSIT=定金+尾款分期支付", example = "FULL")
     private String paymentType;
 
-    @ApiModelProperty(value = "定金比例（百分比）", example = "30")
+    @ApiModelProperty(value = "定金比例（百分比，如30代表30%。与depositAmount二选一，优先使用比例）", example = "30")
     private Integer depositRatio;
 
-    @ApiModelProperty(value = "定金金额", example = "1000.00")
+    @ApiModelProperty(value = "定金金额（固定金额，与depositRatio二选一）", example = "1000.00")
     private BigDecimal depositAmount;
 
-    @ApiModelProperty(value = "尾款支付截止天数（出发前N天）", example = "7")
+    @ApiModelProperty(value = "尾款支付截止天数（出发前N天必须支付尾款，超时可能取消订单）", example = "7")
     private Integer balanceDueDays;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java
index 23e1203..99033be 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java
@@ -10,10 +10,11 @@ import javax.validation.constraints.NotBlank;
 @ApiModel("产品状态变更请求")
 public class ProductStatusRequest {
 
-    @ApiModelProperty(value = "目标状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED", required = true, example = "PUBLISHED")
+    @ApiModelProperty(value = "目标状态。核心/小蒙马：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED；定制产品：COMPLETED",
+            required = true, example = "PUBLISHED")
     @NotBlank(message = "目标状态不能为空")
     private String status;
 
-    @ApiModelProperty(value = "状态变更原因（驳回时必填）", example = "行程信息不完整，请补充")
+    @ApiModelProperty(value = "状态变更原因（驳回时必填；上架/下架审批时可填）", example = "行程信息不完整，请补充")
     private String reason;
 }

`hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java b/hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java
index fd39d97..92c28aa 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java
@@ -21,18 +21,18 @@ public class QuoteRequest {
     @Min(value = 1, message = "成人人数最少1人")
     private Integer adultCount;
 
-    @ApiModelProperty(value = "儿童人数（占床）", example = "1")
+    @ApiModelProperty(value = "儿童人数（占床，按儿童价计算）", example = "1")
     @Min(value = 0, message = "儿童人数不能为负数")
     private Integer childCount = 0;
 
-    @ApiModelProperty(value = "小童人数（不占床）", example = "0")
+    @ApiModelProperty(value = "小童人数（不占床，按儿童价 × childDiscountPercent 折扣比例计算）", example = "0")
     @Min(value = 0, message = "小童人数不能为负数")
     private Integer youngChildCount = 0;
 
-    @ApiModelProperty(value = "婴儿人数", example = "0")
+    @ApiModelProperty(value = "婴儿人数（按固定 babyPrice 计算）", example = "0")
     @Min(value = 0, message = "幼童人数不能为负数")
     private Integer babyCount = 0;
 
-    @ApiModelProperty(value = "儿童是否加床", example = "false")
+    @ApiModelProperty(value = "儿童是否加床（true 时额外加收 childWithBed 费用）", example = "false")
     private Boolean childNeedBed = false;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java
index 46060ff..63b4dc9 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,7 +11,9 @@ import java.util.List;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("批量素材ID请求")
 public class BatchMaterialIdsRequest {
 
+    @ApiModelProperty("素材ID列表")
     private List<Long> materialIds;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java
index e859cea..53c0c3d 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,7 +11,9 @@ import java.util.List;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("批量引用绑定请求")
 public class RefBatchBindRequest {
 
+    @ApiModelProperty("引用绑定列表")
     private List<RefBindRequest> refs;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java
index 965c0e9..b532ee1 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,7 +11,9 @@ import java.util.List;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("批量引用解绑请求")
 public class RefBatchUnbindRequest {
 
+    @ApiModelProperty("引用解绑列表")
     private List<RefUnbindRequest> refs;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java
index 8d95b02..16fdb65 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBindRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -7,11 +9,21 @@ import lombok.NoArgsConstructor;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("引用绑定请求")
 public class RefBindRequest {
 
+    @ApiModelProperty("素材ID")
     private Long materialId;
+
+    @ApiModelProperty("业务类型")
     private String bizType;
+
+    @ApiModelProperty("业务ID")
     private Long bizId;
+
+    @ApiModelProperty("业务名称")
     private String bizName;
+
+    @ApiModelProperty("用途类型")
     private String usageType;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java
index 04252db..cdd7901 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefUnbindRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -7,10 +9,18 @@ import lombok.NoArgsConstructor;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("引用解绑请求")
 public class RefUnbindRequest {
 
+    @ApiModelProperty("素材ID")
     private Long materialId;
+
+    @ApiModelProperty("业务类型")
     private String bizType;
+
+    @ApiModelProperty("业务ID")
     private Long bizId;
+
+    @ApiModelProperty("用途类型")
     private String usageType;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java
index da0d81d..9188dfb 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourceCoverQuery.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -7,7 +9,12 @@ import lombok.NoArgsConstructor;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("资源封面查询")
 public class ResourceCoverQuery {
+
+    @ApiModelProperty("资源类型")
     private String resourceType;
+
+    @ApiModelProperty("资源ID")
     private String resourceId;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java
index 90b98cf..685d2e0 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/dto/ResourcePriceQuery.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -12,16 +14,21 @@ import java.util.List;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("资源价格查询")
 public class ResourcePriceQuery {
 
+    @ApiModelProperty("资源ID列表")
     private List<Long> resourceIds;
 
+    @ApiModelProperty("人员类型列表")
     private List<String> staffTypes;
 
+    @ApiModelProperty("开始日期")
     private LocalDate startDate;
 
+    @ApiModelProperty("结束日期")
     private LocalDate endDate;
 
-    /** resource sub-type (e.g. room_type_id for hotel, vehicle category for vehicle) */
+    @ApiModelProperty("资源子类型(如酒店房型ID、车辆类别)")
     private String subType;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java b/hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java
index d072f29..ec5b204 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/vo/MaterialVO.java
@@ -1,13 +1,25 @@
 package com.hulalv.product.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 @Data
+@ApiModel("素材信息VO")
 public class MaterialVO {
 
+    @ApiModelProperty("素材ID")
     private String materialId;
+
+    @ApiModelProperty("OSS访问URL")
     private String ossUrl;
+
+    @ApiModelProperty("缩略图URL")
     private String thumbnailUrl;
+
+    @ApiModelProperty("素材名称")
     private String materialName;
+
+    @ApiModelProperty("文件类型")
     private String fileType;
 }

`hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java` (M)

diff --git a/hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java b/hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java
index 4cf6dae..232915a 100644
--- a/hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java
+++ b/hl-product-service/src/main/java/com/hulalv/product/feign/vo/ResourcePriceVO.java
@@ -1,5 +1,7 @@
 package com.hulalv.product.feign.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -12,15 +14,21 @@ import java.time.LocalDate;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@ApiModel("资源价格VO")
 public class ResourcePriceVO {
 
+    @ApiModelProperty("资源ID")
     private Long resourceId;
 
+    @ApiModelProperty("人员类型")
     private String staffType;
 
+    @ApiModelProperty("日期")
     private LocalDate date;
 
+    @ApiModelProperty("价格")
     private BigDecimal price;
 
+    @ApiModelProperty("资源名称")
     private String resourceName;
 }

`hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java
index ab64e9e..4015f1e 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java
@@ -26,7 +26,7 @@ public class ActivityController {
 
     private final ActivityService activityService;
 
-    @ApiOperation("创建游玩项目")
+    @ApiOperation(value = "创建游玩项目", notes = "新建游玩项目资源（如漂流、骑行、篝火晚会等），初始状态为草稿(status=0)。需通过「提交启用/禁用审批」走企微审批后上架。支持按项收费(PER_ITEM)和按人收费(PER_PERSON)两种计费方式。\n\n**关联字典**：\n- activity_category：活动分类（表单选择）\n- activity_billing_type：计费方式（表单选择）")
     @PostMapping("/item")
     public Result<ActivityVO> createActivity(
             @ApiParam("游玩项目创建请求") @Valid @RequestBody ActivityCreateRequest request,
@@ -35,19 +35,19 @@ public class ActivityController {
         return Result.success(activityService.createActivity(request, adminId));
     }
 
-    @ApiOperation("游玩项目列表")
+    @ApiOperation(value = "游玩项目列表", notes = "分页查询游玩项目列表，支持按名称、状态、分类等条件筛选。返回摘要信息，按sortOrder倒序+创建时间倒序排列。\n\n**关联字典**：\n- activity_category：活动分类（筛选+列表显示）\n- activity_billing_type：计费方式（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<ActivityListVO>> listActivities(@ApiParam("游玩项目查询请求") @Valid ActivityQueryRequest query) {
         return Result.success(activityService.listActivities(query));
     }
 
-    @ApiOperation("游玩项目详情")
+    @ApiOperation(value = "游玩项目详情", notes = "获取游玩项目完整信息，包含富文本内容、素材URL、标签、价格日历等。\n\n**关联字典**：\n- activity_category：活动分类（详情显示）\n- activity_billing_type：计费方式（详情显示）")
     @GetMapping("/item/{activityId}")
     public Result<ActivityVO> getActivity(@ApiParam("游玩项目ID") @PathVariable Long activityId) {
         return Result.success(activityService.getActivity(activityId));
     }
 
-    @ApiOperation("更新游玩项目")
+    @ApiOperation(value = "更新游玩项目", notes = "更新游玩项目基本信息，不改变当前状态。已上架的项目修改后仍保持上架。\n\n**关联字典**：\n- activity_category：活动分类（表单选择）\n- activity_billing_type：计费方式（表单选择）")
     @PutMapping("/item/{activityId}")
     public Result<ActivityVO> updateActivity(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -57,7 +57,7 @@ public class ActivityController {
         return Result.success(activityService.updateActivity(activityId, request, adminId));
     }
 
-    @ApiOperation("删除游玩项目")
+    @ApiOperation(value = "删除游玩项目", notes = "软删除游玩项目。仅SUPER_ADMIN或创建者可操作。删除后关联的素材引用会被清理。")
     @DeleteMapping("/item/{activityId}")
     public Result<Void> deleteActivity(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -68,7 +68,7 @@ public class ActivityController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。审批通过后自动更新状态，返回审批单号spNo。")
     @PostMapping("/item/{activityId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -80,7 +80,7 @@ public class ActivityController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("启用/禁用切换")
+    @ApiOperation(value = "启用/禁用切换", notes = "直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/item/{activityId}/status")
     public Result<Void> updateStatus(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -91,7 +91,7 @@ public class ActivityController {
         return Result.success();
     }
 
-    @ApiOperation("批量启用/禁用")
+    @ApiOperation(value = "批量启用/禁用", notes = "批量修改多个游玩项目的状态，跳过审批流程。")
     @PutMapping("/items/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("游玩项目状态请求") @Valid @RequestBody ActivityStatusRequest request,
@@ -103,7 +103,7 @@ public class ActivityController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个游玩项目。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/items/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java
index 9fec542..3fff48f 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarController.java
@@ -25,7 +25,7 @@ public class ActivityPriceCalendarController {
 
     private final ActivityPriceCalendarService priceService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询游玩项目的每日价格和可接待状态。")
     @GetMapping("/item/{activityId}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -34,7 +34,7 @@ public class ActivityPriceCalendarController {
         return Result.success(priceService.getPriceCalendar(activityId, year, month));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格", notes = "在指定日期范围内批量设置成本价和可接待状态。支持按星期过滤和排除特定日期。")
     @PutMapping("/item/{activityId}/prices")
     public Result<Void> batchSetPrices(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -43,7 +43,7 @@ public class ActivityPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改可接待状态")
+    @ApiOperation(value = "批量修改可接待状态", notes = "批量修改指定日期范围内的可接待状态，不影响价格。")
     @PutMapping("/item/{activityId}/prices/batch-status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -52,7 +52,7 @@ public class ActivityPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量清除价格")
+    @ApiOperation(value = "批量清除价格", notes = "删除指定日期范围内的所有价格记录。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/item/{activityId}/prices")
     public Result<Void> deletePrices(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,

`hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java
index 2a01cd2..80b72a0 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityTagController.java
@@ -27,7 +27,7 @@ public class ActivityTagController {
 
     private final ActivityTagService tagService;
 
-    @ApiOperation("获取管理标签列表（分页）")
+    @ApiOperation(value = "获取管理标签列表（分页）", notes = "分页查询游玩项目标签库，支持按关键词搜索。包含预设标签和自定义标签。")
     @GetMapping("/tags")
     public Result<PageResult<ActivityTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class ActivityTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("获取全部标签")
+    @ApiOperation(value = "获取全部标签", notes = "不分页返回所有标签，用于项目编辑时的标签选择下拉。")
     @GetMapping("/tags/all")
     public Result<List<ActivityTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建管理标签")
+    @ApiOperation(value = "创建管理标签", notes = "创建预设标签，标签名不可重复。可指定颜色(tagColor)，默认#409EFF。")
     @PostMapping("/tag")
     public Result<ActivityTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class ActivityTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "按名称查找或自动创建标签。用于项目编辑时快速输入新标签。")
     @PostMapping("/tag/adhoc")
     public Result<ActivityTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class ActivityTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("编辑标签")
+    @ApiOperation(value = "编辑标签", notes = "修改标签名称或颜色，所有关联项目自动生效。")
     @PutMapping("/tag/{tagId}")
     public Result<ActivityTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class ActivityTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并自动解除所有项目与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("更新项目标签")
+    @ApiOperation(value = "更新项目标签", notes = "全量替换指定项目的标签列表。传入tagIds为最终关联的标签ID列表，为空则清除所有标签。")
     @PutMapping("/item/{activityId}/tags")
     public Result<Void> updateActivityTags(
             @ApiParam("游玩项目ID") @PathVariable Long activityId,
@@ -87,7 +87,7 @@ public class ActivityTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量打标签")
+    @ApiOperation(value = "批量打标签", notes = "对多个项目批量添加/移除标签。增量操作，不影响未指定的标签。")
     @PutMapping("/items/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {

`hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java
index e24ce98..1b5dd8f 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java
@@ -17,7 +17,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】游玩项目（Feign调用）")
+@Api(tags = "【内部接口】游玩项目（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/activity")
 @RequiredArgsConstructor
@@ -25,7 +25,7 @@ public class InternalActivityController {
 
     private final ActivityService activityService;
 
-    @ApiOperation("获取项目简要信息")
+    @ApiOperation(value = "获取项目简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个游玩项目的简要信息，返回ID、名称、分类编码、计费类型、状态。不存在时返回错误。\n\n**关联字典**：\n- activity_category（活动分类，返回字段categoryCode）：OUTDOOR=户外, INDOOR=室内, CULTURAL=文化, ADVENTURE=探险\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/item/{activityId}")
     public Result<Map<String, Object>> getActivityBrief(@PathVariable Long activityId) {
         Activity item = activityService.getActivityEntity(activityId);
@@ -41,7 +41,7 @@ public class InternalActivityController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取项目简要信息")
+    @ApiOperation(value = "批量获取项目简要信息", notes = "【仅限内部Feign调用】批量获取游玩项目简要信息，最多500个ID。不存在的ID自动过滤，返回实际找到的项目列表。供产品服务批量查询行程节点绑定的活动资源。\n\n**关联字典**：\n- activity_category（活动分类，返回字段categoryCode）：OUTDOOR=户外, INDOOR=室内, CULTURAL=文化, ADVENTURE=探险\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/items/batch")
     public Result<List<Map<String, Object>>> getActivityBatch(@RequestParam @Size(max = 500) List<Long> activityIds) {
         List<Map<String, Object>> results = activityIds.stream()
@@ -61,9 +61,9 @@ public class InternalActivityController {
         return Result.success(results);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo(审批单号)匹配游玩项目并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         activityService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java
index 63164c0..03e9f1d 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalMpActivityController.java
@@ -14,7 +14,7 @@ import org.springframework.web.bind.annotation.*;
 /**
  * C端活动内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  */
-@Api(tags = "【内部接口】小程序活动（Feign调用）")
+@Api(tags = "【内部接口】小程序活动（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/activity")
 @RequiredArgsConstructor
@@ -22,14 +22,14 @@ public class InternalMpActivityController {
 
     private final ActivityService activityService;
 
-    @ApiOperation("C端活动列表")
+    @ApiOperation(value = "C端活动列表", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用。强制status=1只返回已上架活动，支持分页和筛选。C端用户通过小程序间接访问。\n\n**关联字典**：\n- activity_category（活动分类，返回字段categoryCode）：OUTDOOR=户外, INDOOR=室内, CULTURAL=文化, ADVENTURE=探险\n- environment_type（环境类型，返回字段environmentType）：INDOOR=室内, OUTDOOR=户外, MIXED=混合")
     @GetMapping("/list")
     public Result<PageResult<ActivityListVO>> listActivities(ActivityQueryRequest query) {
         query.setStatus(1);
         return Result.success(activityService.listActivities(query));
     }
 
-    @ApiOperation("C端活动详情")
+    @ApiOperation(value = "C端活动详情", notes = "【仅限内部Feign调用】供mp-service获取活动完整详情，包含封面、轮播图、标签、富文本介绍等。注意：不限制status，由BFF层校验是否展示。\n\n**关联字典**：\n- activity_category（活动分类，返回字段categoryCode）：OUTDOOR=户外, INDOOR=室内, CULTURAL=文化, ADVENTURE=探险\n- environment_type（环境类型，返回字段environmentType）：INDOOR=室内, OUTDOOR=户外, MIXED=混合")
     @GetMapping("/{activityId}")
     public Result<ActivityVO> getActivityDetail(@PathVariable Long activityId) {
         ActivityVO vo = activityService.getActivity(activityId);

`hl-resource-service/src/main/java/com/hulalv/resource/config/Knife4jConfig.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/config/Knife4jConfig.java b/hl-resource-service/src/main/java/com/hulalv/resource/config/Knife4jConfig.java
index 88feb5b..21cce9b 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/config/Knife4jConfig.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/config/Knife4jConfig.java
@@ -1,5 +1,6 @@
 package com.hulalv.resource.config;
 
+import com.google.common.base.Predicate;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
@@ -11,12 +12,18 @@ import springfox.documentation.spring.web.plugins.Docket;
 /**
  * Knife4j API文档配置（9个资源领域分组）
  * <p>
- * 为每个资源领域创建独立的API文档分组，便于分类查阅接口
+ * 为每个资源领域创建独立的API文档分组，便于分类查阅接口。
+ * 内部Feign接口（/internal/路径）不在文档中展示。
  * </p>
  */
 @Configuration
 public class Knife4jConfig {
 
+    /** 排除内部接口路径 */
+    private Predicate<String> adminPaths() {
+        return input -> input != null && !input.contains("/internal/") && !input.contains("/callback/");
+    }
+
     /** 景区管理API分组 */
     @Bean
     public Docket scenicApi() {
@@ -29,7 +36,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.resource.scenic.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 
@@ -45,7 +52,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.resource.restaurant.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 
@@ -61,7 +68,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.resource.supplies.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 
@@ -77,7 +84,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.resource.activity.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 
@@ -93,7 +100,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.resource.hotel.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 
@@ -109,7 +116,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.resource.service.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 
@@ -125,7 +132,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.resource.vehicle.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 
@@ -141,7 +148,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.resource.cost.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 
@@ -157,7 +164,7 @@ public class Knife4jConfig {
                         .build())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.hulalv.resource.staff.controller"))
-                .paths(PathSelectors.any())
+                .paths(adminPaths())
                 .build();
     }
 }

`hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java
index 3fcaf95..a7c45f5 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java
@@ -40,7 +40,7 @@ import java.util.stream.Collectors;
  */
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】资源摘要（Feign调用）")
+@Api(tags = "【内部接口】资源摘要（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/resource")
 @RequiredArgsConstructor
@@ -60,7 +60,7 @@ public class InternalMpResourceBriefController {
 
     private final MaterialRefFeignClient materialRefClient;
 
-    @ApiOperation("批量查询景区摘要")
+    @ApiOperation(value = "批量查询景区摘要", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用（收藏列表/足迹列表），返回最小化信息：id、name、coverUrl、tags。最多500个ID。")
     @GetMapping("/scenic/brief")
     public Result<List<Map<String, Object>>> getScenicBrief(@RequestParam @Size(max = 500) List<Long> ids) {
         if (ids == null || ids.isEmpty()) {
@@ -94,7 +94,7 @@ public class InternalMpResourceBriefController {
         return Result.success(result);
     }
 
-    @ApiOperation("批量查询餐厅摘要")
+    @ApiOperation(value = "批量查询餐厅摘要", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用，返回最小化信息。最多500个ID。")
     @GetMapping("/restaurant/brief")
     public Result<List<Map<String, Object>>> getRestaurantBrief(@RequestParam @Size(max = 500) List<Long> ids) {
         if (ids == null || ids.isEmpty()) {
@@ -126,7 +126,7 @@ public class InternalMpResourceBriefController {
         return Result.success(result);
     }
 
-    @ApiOperation("批量查询活动摘要")
+    @ApiOperation(value = "批量查询活动摘要", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用，返回最小化信息。最多500个ID。")
     @GetMapping("/activity/brief")
     public Result<List<Map<String, Object>>> getActivityBrief(@RequestParam @Size(max = 500) List<Long> ids) {
         if (ids == null || ids.isEmpty()) {

`hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java
index d4158a8..44cd22e 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceController.java
@@ -25,7 +25,7 @@ import org.springframework.web.bind.annotation.*;
  * </p>
  */
 @Slf4j
-@Api(tags = "【内部接口】资源审批（Feign调用）")
+@Api(tags = "【内部接口】资源审批（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/resource")
 @RequiredArgsConstructor
@@ -42,9 +42,9 @@ public class InternalResourceController {
     private final StaffService staffService;
 
     /** 处理审批回调 - 分发到9个资源领域服务 */
-    @ApiOperation("处理审批回调 - 分发到9个资源领域服务")
+    @ApiOperation(value = "处理审批回调 - 分发到9个资源领域服务", notes = "【仅限内部Feign调用】接收企微审批回调结果，按thirdNo(审批单号)在9个资源领域中匹配并更新状态。每个领域服务内部通过approval_no匹配，未找到则忽略（幂等处理）。由hl-callback-service通过MQ消费后调用。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
 
         // 分发到9个领域服务 - 每个服务内部检查approval_no

`hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java
index a6adb66..e726a14 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java
@@ -41,7 +41,7 @@ import java.util.stream.Collectors;
  * 供产品服务的行程节点获取绑定资源的详细信息（含图片、地址等）
  */
 @Slf4j
-@Api(tags = "【内部接口】资源详情（Feign调用）")
+@Api(tags = "【内部接口】资源详情（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/resource")
 @RequiredArgsConstructor
@@ -69,7 +69,7 @@ public class InternalResourceDetailController {
      * @param activityIds   活动ID列表
      * @return resourceType:resourceId → ResourceDetailDTO
      */
-    @ApiOperation("批量查询资源详情（行程节点用）")
+    @ApiOperation(value = "批量查询资源详情（行程节点用）", notes = "【仅限内部Feign调用】供产品服务获取行程节点绑定资源的详细信息。按类型分组查询，返回Map<resourceType:resourceId, ResourceDetailDTO>。包含封面、轮播图URL、地址、坐标、标签、富文本介绍等完整信息。\n\n**关联字典**：\n- city（城市，返回字段city）")
     @GetMapping("/batch-details")
     public Result<Map<String, ResourceDetailDTO>> batchDetails(
             @RequestParam(required = false) List<Long> scenicIds,

`hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java
index 366168b..e1ddd03 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java
@@ -53,7 +53,7 @@ import java.util.stream.Collectors;
 @RestController
 @RequestMapping("/internal/resource/prices")
 @RequiredArgsConstructor
-@Api(tags = "【内部接口】资源价格（Feign调用）")
+@Api(tags = "【内部接口】资源价格（Feign调用）", hidden = true)
 public class InternalResourcePriceController {
 
     private final ScenicPriceCalendarMapper scenicPriceMapper;
@@ -71,7 +71,7 @@ public class InternalResourcePriceController {
     private final SuppliesItemMapper suppliesItemMapper;
     private final SuppliesService suppliesService;
 
-    /** 查询景区价格 */
+    /** 查询景区价格 - 按景区ID和日期范围查询价格日历的成本价 */
     @PostMapping("/scenic")
     public Result<List<PriceVO>> getScenicPrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -108,7 +108,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询酒店价格（按hotelId查最低房型价格） */
+    /** 查询酒店价格 - 按hotelId查询日期范围内最低房型的成本价（取所有房型中最低价） */
     @PostMapping("/hotel")
     public Result<List<PriceVO>> getHotelPrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -143,7 +143,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询房型价格（按roomTypeId精确查询） */
+    /** 查询房型价格 - 按roomTypeId精确查询日期范围内的成本价（取最低价） */
     @PostMapping("/room-type")
     public Result<List<PriceVO>> getRoomTypePrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -178,7 +178,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询活动价格 */
+    /** 查询活动价格 - 按活动ID和日期范围查询价格日历的成本价 */
     @PostMapping("/activity")
     public Result<List<PriceVO>> getActivityPrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -214,7 +214,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询车辆价格 */
+    /** 查询车辆价格 - 按车型ID和日期范围查询价格日历的成本价 */
     @PostMapping("/vehicle")
     public Result<List<PriceVO>> getVehiclePrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -250,7 +250,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询服务项价格 */
+    /** 查询服务项价格 - 按服务项ID和日期范围查询价格日历的成本价 */
     @PostMapping("/service")
     public Result<List<PriceVO>> getServicePrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -283,13 +283,13 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询餐厅价格（餐厅无价格日历，返回空） */
+    /** 查询餐厅价格 - 餐厅无独立价格日历，始终返回空列表（餐费通过费用项管理） */
     @PostMapping("/restaurant")
     public Result<List<PriceVO>> getRestaurantPrices(@RequestBody PriceQuery query) {
         return Result.success(new ArrayList<>());
     }
 
-    /** 查询服务人员价格（按人员类型） */
+    /** 查询服务人员价格 - 按staffType(人员类型)和日期范围查询价格日历的成本价（人员价格按类型而非个人） */
     @PostMapping("/staff")
     public Result<List<PriceVO>> getStaffPrices(@RequestBody PriceQuery query) {
         List<PriceVO> results = new ArrayList<>();
@@ -321,7 +321,7 @@ public class InternalResourcePriceController {
         return Result.success(results);
     }
 
-    /** 查询酒店下所有房型（简要信息） */
+    /** 查询酒店下所有已启用房型 - 返回roomTypeId、name、maxOccupancy、basePrice，按sortOrder排序 */
     @GetMapping("/room-types-by-hotel/{hotelId}")
     public Result<List<RoomTypeSimpleVO>> getRoomTypesByHotel(@PathVariable Long hotelId) {
         List<RoomType> roomTypes = roomTypeMapper.selectList(
@@ -336,7 +336,7 @@ public class InternalResourcePriceController {
         return Result.success(vos);
     }
 
-    /** 查询所有可用车型（简要信息） */
+    /** 查询所有已启用车型 - 返回vehicleId、name、seatCount、basePrice，按sortOrder排序，供产品服务车辆下拉选择使用 */
     @GetMapping("/vehicle-models")
     public Result<List<VehicleSimpleVO>> getVehicleModels() {
         List<VehicleModel> vehicles = vehicleModelMapper.selectList(

`hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java
index 019a26f..3ef23db 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceStatsController.java
@@ -14,7 +14,7 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.HashMap;
 import java.util.Map;
 
-@Api(tags = "【内部接口】资源统计（Feign调用）")
+@Api(tags = "【内部接口】资源统计（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/resource")
 @RequiredArgsConstructor
@@ -24,7 +24,7 @@ public class InternalResourceStatsController {
     private final RoomTypeMapper roomTypeMapper;
     private final VehicleModelMapper vehicleModelMapper;
 
-    @ApiOperation("获取酒店统计")
+    @ApiOperation(value = "获取酒店统计", notes = "【仅限内部Feign调用】返回酒店总数和房型总数，供管理后台仪表盘展示。")
     @GetMapping("/hotel/stats")
     public Result<Map<String, Object>> getHotelStats() {
         long totalHotels = hotelMapper.selectCount(null);
@@ -36,7 +36,7 @@ public class InternalResourceStatsController {
         return Result.success(stats);
     }
 
-    @ApiOperation("获取车辆统计")
+    @ApiOperation(value = "获取车辆统计", notes = "【仅限内部Feign调用】返回车型总数，供管理后台仪表盘展示。")
     @GetMapping("/vehicle/stats")
     public Result<Map<String, Object>> getVehicleStats() {
         long totalVehicles = vehicleModelMapper.selectCount(null);

`hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java
index ce21f8c..b138078 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostItemController.java
@@ -28,7 +28,7 @@ public class CostItemController {
 
     private final CostItemService costItemService;
 
-    @ApiOperation("创建费用项")
+    @ApiOperation(value = "创建费用项", notes = "新建费用项（如门票成本、餐费、保险费等），用于产品报价计算。费用项有独立的价格日历，价格变更会记录变更日志。创建后需走企微审批上架。\n\n**关联字典**：\n- cost_category：费用分类（表单选择）\n- cost_apply_role：适用角色（表单选择）\n- cost_unit：计量单位（表单选择）")
     @PostMapping("/item")
     public Result<CostItemVO> createCostItem(@ApiParam("费用项创建请求") @Valid @RequestBody CostItemCreateRequest request,
                                               HttpServletRequest httpRequest) {
@@ -36,19 +36,19 @@ public class CostItemController {
         return Result.success(costItemService.createCostItem(request, adminId));
     }
 
-    @ApiOperation("费用项列表")
+    @ApiOperation(value = "费用项列表", notes = "分页查询费用项列表，支持按名称、状态等条件筛选。\n\n**关联字典**：\n- cost_category：费用分类（筛选+列表显示）\n- cost_apply_role：适用角色（筛选+列表显示）\n- cost_unit：计量单位（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<CostItemListVO>> listCostItems(@ApiParam("费用项查询请求") @Valid CostItemQueryRequest query) {
         return Result.success(costItemService.listCostItems(query));
     }
 
-    @ApiOperation("费用项详情")
+    @ApiOperation(value = "费用项详情", notes = "获取费用项完整信息，包含当前价格、引用计数等。\n\n**关联字典**：\n- cost_category：费用分类（详情显示）\n- cost_apply_role：适用角色（详情显示）\n- cost_unit：计量单位（详情显示）")
     @GetMapping("/item/{costId}")
     public Result<CostItemVO> getCostItem(@ApiParam("费用项ID") @PathVariable Long costId) {
         return Result.success(costItemService.getCostItem(costId));
     }
 
-    @ApiOperation("更新费用项")
+    @ApiOperation(value = "更新费用项", notes = "更新费用项信息。如果修改了价格，会自动记录价格变更日志。\n\n**关联字典**：\n- cost_category：费用分类（表单选择）\n- cost_apply_role：适用角色（表单选择）\n- cost_unit：计量单位（表单选择）")
     @PutMapping("/item/{costId}")
     public Result<CostItemVO> updateCostItem(@ApiParam("费用项ID") @PathVariable Long costId,
                                               @ApiParam("费用项更新请求") @Valid @RequestBody CostItemUpdateRequest request,
@@ -57,7 +57,7 @@ public class CostItemController {
         return Result.success(costItemService.updateCostItem(costId, request, adminId));
     }
 
-    @ApiOperation("删除费用项")
+    @ApiOperation(value = "删除费用项", notes = "软删除费用项。仅SUPER_ADMIN或创建者可操作。被产品引用(refCount>0)的费用项不建议删除。")
     @DeleteMapping("/item/{costId}")
     public Result<Void> deleteCostItem(@ApiParam("费用项ID") @PathVariable Long costId, HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);
@@ -66,7 +66,7 @@ public class CostItemController {
         return Result.success();
     }
 
-    @ApiOperation("提交审批")
+    @ApiOperation(value = "提交审批", notes = "向企微OA提交费用项启用/禁用审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。")
     @PostMapping("/item/{costId}/submit-approval")
     public Result<java.util.Map<String, String>> submitApproval(@ApiParam("费用项ID") @PathVariable Long costId,
                                                                 @ApiParam("审批提交请求体") @Valid @RequestBody ApprovalSubmitRequest request,
@@ -76,13 +76,13 @@ public class CostItemController {
         return Result.success(java.util.Map.of("spNo", spNo));
     }
 
-    @ApiOperation("启用的费用项列表")
+    @ApiOperation(value = "启用的费用项列表", notes = "查询所有已启用(status=1)的费用项，不分页。用于产品编排时选择费用项的下拉列表。\n\n**关联字典**：\n- cost_category：费用分类（列表显示）\n- cost_apply_role：适用角色（列表显示）\n- cost_unit：计量单位（列表显示）")
     @GetMapping("/items/enabled")
     public Result<List<CostItemVO>> listEnabledCostItems() {
         return Result.success(costItemService.listEnabledCostItems());
     }
 
-    @ApiOperation("费用项价格变更记录")
+    @ApiOperation(value = "费用项价格变更记录", notes = "查询费用项的历史价格变更记录，按时间倒序排列。用于追溯价格调整历史。")
     @GetMapping("/item/{costId}/price-logs")
     public Result<List<CostPriceLogVO>> getPriceLogs(@ApiParam("费用项ID") @PathVariable Long costId) {
         return Result.success(costItemService.getPriceLogs(costId));

`hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java
index 862c1b2..95007f0 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/CostPriceCalendarController.java
@@ -26,7 +26,7 @@ public class CostPriceCalendarController {
 
     private final CostPriceCalendarService priceCalendarService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询费用项的每日价格。费用项价格日历用于产品报价计算时按日期获取成本价。")
     @GetMapping("/item/{costId}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(@ApiParam("费用项ID") @PathVariable Long costId,
                                                      @ApiParam("年份") @RequestParam @Min(2020) @Max(2100) Integer year,
@@ -34,7 +34,7 @@ public class CostPriceCalendarController {
         return Result.success(priceCalendarService.getPriceCalendar(costId, year, month));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格", notes = "在指定日期范围内批量设置费用项的成本价。")
     @PutMapping("/item/{costId}/prices")
     public Result<Void> batchSetPrices(@ApiParam("费用项ID") @PathVariable Long costId,
                                         @ApiParam("价格日历设置请求") @Valid @RequestBody PriceCalendarSetRequest request) {
@@ -42,7 +42,7 @@ public class CostPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("清除价格日历")
+    @ApiOperation(value = "清除价格日历", notes = "删除指定日期范围内费用项的价格记录。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/item/{costId}/prices")
     public Result<Void> deletePrices(@ApiParam("费用项ID") @PathVariable Long costId,
                                       @ApiParam("开始日期") @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate startDate,

`hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java
index 5e27f64..361c8de 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/cost/controller/InternalCostController.java
@@ -20,7 +20,7 @@ import java.util.Map;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】费用项（Feign调用）")
+@Api(tags = "【内部接口】费用项（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/cost")
 @RequiredArgsConstructor
@@ -28,21 +28,21 @@ public class InternalCostController {
 
     private final CostItemService costItemService;
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配费用项并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         costItemService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();
     }
 
-    @ApiOperation("批量获取费用项")
+    @ApiOperation(value = "批量获取费用项", notes = "【仅限内部Feign调用】批量获取费用项完整信息（含名称、分类、计费类型、基础价格等），最多500个ID。供产品服务批量查询产品关联的费用项。\n\n**关联字典**：\n- cost_unit（计费单位，返回字段unit）：PER_PERSON=元/人, PER_VEHICLE=元/台, PER_DAY=元/天, PER_TIME=元/次, PER_ROOM=元/间, PER_TABLE=元/桌, FIXED=固定金额\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/items/batch")
     public Result<List<CostItemVO>> batchGetCostItems(@RequestParam @Size(max = 500) List<Long> costIds) {
         return Result.success(costItemService.batchGetCostItems(costIds));
     }
 
-    @ApiOperation("按日期获取费用项价格")
+    @ApiOperation(value = "按日期获取费用项价格", notes = "【仅限内部Feign调用】按指定日期批量查询费用项的成本价格。返回Map<costId字符串, 价格>。优先取价格日历，无日历则取basePrice。供产品服务报价计算器使用。")
     @GetMapping("/items/prices-by-date")
     public Result<Map<String, BigDecimal>> getByDatePrices(
             @RequestParam @Size(max = 500) List<Long> costIds,
@@ -50,7 +50,7 @@ public class InternalCostController {
         return Result.success(costItemService.getByDatePrices(costIds, date));
     }
 
-    @ApiOperation("更新引用计数")
+    @ApiOperation(value = "更新引用计数", notes = "【仅限内部Feign调用】更新费用项的引用计数。delta>0表示新增引用，delta<0表示减少引用。供产品服务在关联/取消关联费用项时调用，用于统计资源被使用次数。")
     @PostMapping("/item/{costId}/ref-count")
     public Result<Void> updateRefCount(@PathVariable Long costId, @RequestParam int delta) {
         costItemService.updateRefCount(costId, delta);

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java
index 4a0c2c5..7faaef1 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java
@@ -26,7 +26,7 @@ public class HotelController {
 
     private final HotelService hotelService;
 
-    @ApiOperation("创建住宿")
+    @ApiOperation(value = "创建住宿", notes = "新建住宿资源（酒店/民宿/营地等），初始状态为草稿(status=0)。创建后需通过「提交启用/禁用审批」走企微OA审批流程才能上架。住宿下可继续创建房型（RoomType），房型有独立的价格日历。\n\n**关联字典**：\n- hotel_type：住宿类型（表单选择）\n- hotel_star_level：酒店星级（表单选择）\n- hotel_facility：酒店设施（表单多选）")
     @PostMapping("/item")
     public Result<HotelVO> createHotel(
             @ApiParam("住宿创建请求") @Valid @RequestBody HotelCreateRequest request,
@@ -35,25 +35,25 @@ public class HotelController {
         return Result.success(hotelService.createHotel(request, adminId));
     }
 
-    @ApiOperation("住宿列表")
+    @ApiOperation(value = "住宿列表", notes = "分页查询住宿列表，支持按名称关键词、状态、住宿类型等条件筛选。返回列表摘要信息，按sortOrder倒序+创建时间倒序排列。\n\n**关联字典**：\n- hotel_type：住宿类型（筛选+列表显示）\n- hotel_star_level：酒店星级（筛选+列表显示）\n- hotel_facility：酒店设施（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<HotelListVO>> listHotels(@ApiParam("住宿查询请求") @Valid HotelQueryRequest query) {
         return Result.success(hotelService.listHotels(query));
     }
 
-    @ApiOperation("所有启用的住宿（不分页，仅ID和名称）")
+    @ApiOperation(value = "所有启用的住宿（不分页，仅ID和名称）", notes = "返回所有已上架(status=1)的住宿简要信息，用于下拉选择框。每项只含hotelId和name字段。适用于房型管理时选择所属住宿、产品编排时绑定住宿资源等场景。")
     @GetMapping("/items/all-simple")
     public Result<List<Map<String, Object>>> listAllSimple() {
         return Result.success(hotelService.listAllSimple());
     }
 
-    @ApiOperation("住宿详情")
+    @ApiOperation(value = "住宿详情", notes = "获取住宿完整信息，包含素材URL、标签列表、房型列表等。素材ID会自动解析为OSS访问地址。\n\n**关联字典**：\n- hotel_type：住宿类型（详情显示）\n- hotel_star_level：酒店星级（详情显示）\n- hotel_facility：酒店设施（详情显示）")
     @GetMapping("/item/{hotelId}")
     public Result<HotelVO> getHotel(@ApiParam("住宿ID") @PathVariable Long hotelId) {
         return Result.success(hotelService.getHotel(hotelId));
     }
 
-    @ApiOperation("更新住宿")
+    @ApiOperation(value = "更新住宿", notes = "更新住宿基本信息。更新不会改变当前状态，已上架的住宿修改后仍保持上架状态。\n\n**关联字典**：\n- hotel_type：住宿类型（表单选择）\n- hotel_star_level：酒店星级（表单选择）\n- hotel_facility：酒店设施（表单多选）")
     @PutMapping("/item/{hotelId}")
     public Result<HotelVO> updateHotel(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -63,7 +63,7 @@ public class HotelController {
         return Result.success(hotelService.updateHotel(hotelId, request, adminId));
     }
 
-    @ApiOperation("删除住宿")
+    @ApiOperation(value = "删除住宿", notes = "软删除住宿。仅SUPER_ADMIN或创建者可操作。删除住宿会同时删除其下所有房型和价格日历数据。")
     @DeleteMapping("/item/{hotelId}")
     public Result<Void> deleteHotel(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -74,7 +74,7 @@ public class HotelController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交住宿启用/禁用审批。targetStatus=1申请上架，targetStatus=2申请下架。审批通过后自动更新状态。返回企微审批单号spNo。")
     @PostMapping("/item/{hotelId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -86,7 +86,7 @@ public class HotelController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("启用/禁用切换")
+    @ApiOperation(value = "启用/禁用切换", notes = "直接修改住宿状态（跳过审批），仅限SUPER_ADMIN使用。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/item/{hotelId}/status")
     public Result<Void> updateStatus(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -97,7 +97,7 @@ public class HotelController {
         return Result.success();
     }
 
-    @ApiOperation("批量启用/禁用")
+    @ApiOperation(value = "批量启用/禁用", notes = "批量修改多个住宿的状态，跳过审批流程。hotelIds为住宿ID列表（字符串格式）。")
     @PutMapping("/items/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("住宿状态请求") @Valid @RequestBody HotelStatusRequest request,
@@ -109,7 +109,7 @@ public class HotelController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个住宿及其关联的房型和价格日历。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/items/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java
index 3b229f8..02e8708 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java
@@ -27,7 +27,7 @@ public class HotelTagController {
 
     private final HotelTagService tagService;
 
-    @ApiOperation("预设标签列表（分页）")
+    @ApiOperation(value = "预设标签列表（分页）", notes = "分页查询住宿标签库，支持按关键词搜索。")
     @GetMapping("/tags")
     public Result<PageResult<HotelTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class HotelTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("所有标签列表")
+    @ApiOperation(value = "所有标签列表", notes = "不分页返回所有标签，用于住宿编辑时的标签选择。")
     @GetMapping("/tags/all")
     public Result<List<HotelTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建标签")
+    @ApiOperation(value = "创建标签", notes = "创建预设标签，标签名不可重复。")
     @PostMapping("/tag")
     public Result<HotelTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class HotelTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("查找或创建自定义标签")
+    @ApiOperation(value = "查找或创建自定义标签", notes = "按名称查找标签，不存在则自动创建。用于住宿编辑时快速输入新标签。")
     @PostMapping("/tag/adhoc")
     public Result<HotelTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class HotelTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("更新标签")
+    @ApiOperation(value = "更新标签", notes = "修改标签名称或颜色，所有关联住宿自动生效。")
     @PutMapping("/tag/{tagId}")
     public Result<HotelTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class HotelTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并解除所有住宿与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("设置住宿标签")
+    @ApiOperation(value = "设置住宿标签", notes = "全量替换指定住宿的标签列表。")
     @PutMapping("/item/{hotelId}/tags")
     public Result<Void> updateHotelTags(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -87,7 +87,7 @@ public class HotelTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量添加/移除标签")
+    @ApiOperation(value = "批量添加/移除标签", notes = "对多个住宿批量添加/移除标签。增量操作，不影响未指定的标签。")
     @PutMapping("/items/batch/tags")
     public Result<Void> batchUpdateTags(@ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {
         List<Long> hotelIds = request.getHotelIds().stream()

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java
index c758f6e..4b81939 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalHotelController.java
@@ -18,7 +18,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】住宿（Feign调用）")
+@Api(tags = "【内部接口】住宿（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/hotel")
 @RequiredArgsConstructor
@@ -27,7 +27,7 @@ public class InternalHotelController {
     private final HotelService hotelService;
     private final RoomTypeService roomTypeService;
 
-    @ApiOperation("获取住宿简要信息")
+    @ApiOperation(value = "获取住宿简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个住宿的简要信息，返回ID、名称、住宿类型、状态。不存在时返回错误。\n\n**关联字典**：\n- hotel_type（住宿类型，返回字段hotelType）：HOTEL=酒店, GUESTHOUSE=民宿, RESORT=度假村, CAMP=营地, HOMESTAY=农家院\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/item/{hotelId}")
     public Result<Map<String, Object>> getHotelBrief(@PathVariable Long hotelId) {
         Hotel item = hotelService.getHotelEntity(hotelId);
@@ -42,7 +42,7 @@ public class InternalHotelController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取住宿简要信息")
+    @ApiOperation(value = "批量获取住宿简要信息", notes = "【仅限内部Feign调用】批量获取住宿简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询行程节点绑定的住宿资源。\n\n**关联字典**：\n- hotel_type（住宿类型，返回字段hotelType）：HOTEL=酒店, GUESTHOUSE=民宿, RESORT=度假村, CAMP=营地, HOMESTAY=农家院\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/items/batch")
     public Result<List<Map<String, Object>>> getHotelBatch(@RequestParam @Size(max = 500) List<Long> hotelIds) {
         List<Map<String, Object>> results = hotelIds.stream()
@@ -61,9 +61,9 @@ public class InternalHotelController {
         return Result.success(results);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配住宿和房型并更新启用/禁用状态。住宿和房型共享同一审批模板，此接口同时尝试匹配两者。由hl-callback-service通过MQ消费后调用。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         hotelService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         // Also try room type (same template, same callback)

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java
index ce4fd47..2a820f5 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java
@@ -14,7 +14,7 @@ import org.springframework.web.bind.annotation.*;
 /**
  * C端住宿内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  */
-@Api(tags = "【内部接口】小程序酒店（Feign调用）")
+@Api(tags = "【内部接口】小程序酒店（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/hotel")
 @RequiredArgsConstructor
@@ -22,7 +22,7 @@ public class InternalMpHotelController {
 
     private final HotelService hotelService;
 
-    @ApiOperation("C端住宿列表")
+    @ApiOperation(value = "C端住宿列表", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用。强制status=1只返回已上架住宿，支持分页和筛选。C端用户通过小程序间接访问。\n\n**关联字典**：\n- hotel_type（住宿类型，返回字段hotelType）：HOTEL=酒店, GUESTHOUSE=民宿, RESORT=度假村, CAMP=营地, HOMESTAY=农家院\n- hotel_star（星级，返回字段starLevel）：FIVE=五星, FOUR=四星, THREE=三星, UNRATED=未评级")
     @GetMapping("/list")
     public Result<PageResult<HotelListVO>> listHotels(HotelQueryRequest query) {
         // Force status=1 for C-side (only show published hotels)
@@ -30,7 +30,7 @@ public class InternalMpHotelController {
         return Result.success(hotelService.listHotels(query));
     }
 
-    @ApiOperation("C端住宿详情")
+    @ApiOperation(value = "C端住宿详情", notes = "【仅限内部Feign调用】供mp-service获取住宿完整详情，包含房型列表、封面、轮播图、地址等。注意：不限制status，由BFF层校验是否展示。\n\n**关联字典**：\n- hotel_type（住宿类型，返回字段hotelType）：HOTEL=酒店, GUESTHOUSE=民宿, RESORT=度假村, CAMP=营地, HOMESTAY=农家院\n- hotel_star（星级，返回字段starLevel）：FIVE=五星, FOUR=四星, THREE=三星, UNRATED=未评级")
     @GetMapping("/{hotelId}")
     public Result<HotelVO> getHotelDetail(@PathVariable Long hotelId) {
         HotelVO vo = hotelService.getHotel(hotelId);

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java
index cf6df6c..d883d85 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarController.java
@@ -25,7 +25,7 @@ public class RoomPriceCalendarController {
 
     private final RoomPriceCalendarService priceCalendarService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询房型的每日价格和可售状态。每个房型有独立的价格日历。")
     @GetMapping("/room-type/{roomTypeId}/prices")
     public Result<RoomPriceCalendarVO> getPriceCalendar(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,
@@ -34,7 +34,7 @@ public class RoomPriceCalendarController {
         return Result.success(priceCalendarService.getPriceCalendar(roomTypeId, year, month));
     }
 
-    @ApiOperation("批量设置价格日历")
+    @ApiOperation(value = "批量设置价格日历", notes = "在指定日期范围内批量设置房型的成本价和可售状态。支持按星期过滤和排除特定日期。")
     @PutMapping("/room-type/{roomTypeId}/prices")
     public Result<Void> batchSetPrices(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,
@@ -43,7 +43,7 @@ public class RoomPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改日期可售状态")
+    @ApiOperation(value = "批量修改日期可售状态", notes = "批量修改指定日期范围内房型的可售状态，不影响价格。")
     @PutMapping("/room-type/{roomTypeId}/prices/batch-status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,
@@ -52,7 +52,7 @@ public class RoomPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("删除价格日历")
+    @ApiOperation(value = "删除价格日历", notes = "删除指定日期范围内房型的所有价格记录。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/room-type/{roomTypeId}/prices")
     public Result<Void> deletePrices(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,

`hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java
index 2048f4c..0d9cf42 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java
@@ -26,7 +26,7 @@ public class RoomTypeController {
 
     private final RoomTypeService roomTypeService;
 
-    @ApiOperation("创建房型")
+    @ApiOperation(value = "创建房型", notes = "在指定住宿下创建房型（如标准间、大床房、套房等）。每个房型有独立的价格日历、最大入住人数(maxOccupancy)和基础价格(basePrice)。房型初始状态为草稿(status=0)，需独立审批后才能启用。创建后可通过「提交房型启用审批」接口提交企微OA审批。\n\n**关联字典**：\n- room_category：房型分类（表单选择）\n- bed_type：床型（表单选择）\n- window_type：窗户类型（表单选择）\n- bathroom_type：卫浴类型（表单选择）\n- room_facility：房间设施（表单多选）")
     @PostMapping("/{hotelId}/room-type")
     public Result<RoomTypeVO> createRoomType(
             @ApiParam("住宿ID") @PathVariable Long hotelId,
@@ -36,19 +36,19 @@ public class RoomTypeController {
         return Result.success(roomTypeService.createRoomType(hotelId, request, adminId));
     }
 
-    @ApiOperation("房型列表")
+    @ApiOperation(value = "房型列表", notes = "获取指定住宿下的所有房型列表（不分页），按sortOrder排序。\n\n**关联字典**：\n- room_category：房型分类（列表/详情显示）\n- bed_type：床型（列表/详情显示）\n- window_type：窗户类型（列表/详情显示）\n- bathroom_type：卫浴类型（列表/详情显示）\n- room_facility：房间设施（列表/详情显示）")
     @GetMapping("/{hotelId}/room-types")
     public Result<List<RoomTypeVO>> listRoomTypes(@ApiParam("住宿ID") @PathVariable Long hotelId) {
         return Result.success(roomTypeService.listRoomTypes(hotelId));
     }
 
-    @ApiOperation("房型详情")
+    @ApiOperation(value = "房型详情", notes = "获取房型完整信息，包含价格、入住人数、素材等。\n\n**关联字典**：\n- room_category：房型分类（列表/详情显示）\n- bed_type：床型（列表/详情显示）\n- window_type：窗户类型（列表/详情显示）\n- bathroom_type：卫浴类型（列表/详情显示）\n- room_facility：房间设施（列表/详情显示）")
     @GetMapping("/room-type/{roomTypeId}")
     public Result<RoomTypeVO> getRoomType(@ApiParam("房型ID") @PathVariable Long roomTypeId) {
         return Result.success(roomTypeService.getRoomType(roomTypeId));
     }
 
-    @ApiOperation("更新房型")
+    @ApiOperation(value = "更新房型", notes = "更新房型基本信息，不改变当前状态。\n\n**关联字典**：\n- room_category：房型分类（表单选择）\n- bed_type：床型（表单选择）\n- window_type：窗户类型（表单选择）\n- bathroom_type：卫浴类型（表单选择）\n- room_facility：房间设施（表单多选）")
     @PutMapping("/room-type/{roomTypeId}")
     public Result<RoomTypeVO> updateRoomType(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,
@@ -58,14 +58,14 @@ public class RoomTypeController {
         return Result.success(roomTypeService.updateRoomType(roomTypeId, request, adminId));
     }
 
-    @ApiOperation("删除房型")
+    @ApiOperation(value = "删除房型", notes = "软删除房型及其价格日历数据。")
     @DeleteMapping("/room-type/{roomTypeId}")
     public Result<Void> deleteRoomType(@ApiParam("房型ID") @PathVariable Long roomTypeId) {
         roomTypeService.deleteRoomType(roomTypeId);
         return Result.success();
     }
 
-    @ApiOperation("启用/禁用房型")
+    @ApiOperation(value = "启用/禁用房型", notes = "直接修改房型状态（跳过审批）。status=0禁用，status=1启用。禁用后该房型不会出现在C端展示中。")
     @PutMapping("/room-type/{roomTypeId}/status")
     public Result<Void> updateRoomTypeStatus(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,
@@ -74,7 +74,7 @@ public class RoomTypeController {
         return Result.success();
     }
 
-    @ApiOperation("提交房型启用/禁用审批")
+    @ApiOperation(value = "提交房型启用/禁用审批", notes = "向企微OA提交房型启用/禁用审批。审批流程与住宿共享同一模板。返回审批单号spNo。")
     @PostMapping("/room-type/{roomTypeId}/submit-approval")
     public Result<Map<String, String>> submitRoomTypeApproval(
             @ApiParam("房型ID") @PathVariable Long roomTypeId,

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java
index 41d485f..df17f5c 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantController.java
@@ -14,7 +14,7 @@ import org.springframework.web.bind.annotation.*;
 /**
  * C端餐厅内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  */
-@Api(tags = "【内部接口】小程序餐厅（Feign调用）")
+@Api(tags = "【内部接口】小程序餐厅（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/restaurant")
 @RequiredArgsConstructor
@@ -22,7 +22,7 @@ public class InternalMpRestaurantController {
 
     private final RestaurantService restaurantService;
 
-    @ApiOperation("C端餐厅列表")
+    @ApiOperation(value = "C端餐厅列表", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用。强制status=1只返回已上架餐厅，支持分页和筛选。C端用户通过小程序间接访问。\n\n**关联字典**：\n- restaurant_category（餐厅分类，返回字段categoryCode）：CHINESE=中餐, WESTERN=西餐, BBQ=烧烤, HOTPOT=火锅, LOCAL=当地特色")
     @GetMapping("/list")
     public Result<PageResult<RestaurantListVO>> listRestaurants(RestaurantQueryRequest query) {
         // Force status=1 for C-side (only show published restaurants)
@@ -30,7 +30,7 @@ public class InternalMpRestaurantController {
         return Result.success(restaurantService.listRestaurants(query));
     }
 
-    @ApiOperation("C端餐厅详情")
+    @ApiOperation(value = "C端餐厅详情", notes = "【仅限内部Feign调用】供mp-service获取餐厅完整详情，包含封面、轮播图、标签、地址、富文本介绍等。注意：不限制status，由BFF层校验是否展示。\n\n**关联字典**：\n- restaurant_category（餐厅分类，返回字段categoryCode）：CHINESE=中餐, WESTERN=西餐, BBQ=烧烤, HOTPOT=火锅, LOCAL=当地特色")
     @GetMapping("/{restaurantId}")
     public Result<RestaurantVO> getRestaurantDetail(@PathVariable Long restaurantId) {
         RestaurantVO vo = restaurantService.getRestaurant(restaurantId);

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java
index ac8e4db..a87aaea 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/InternalRestaurantController.java
@@ -17,7 +17,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】餐厅（Feign调用）")
+@Api(tags = "【内部接口】餐厅（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/restaurant")
 @RequiredArgsConstructor
@@ -25,7 +25,7 @@ public class InternalRestaurantController {
 
     private final RestaurantService restaurantService;
 
-    @ApiOperation("\u83b7\u53d6\u9910\u5385\u7b80\u8981\u4fe1\u606f")
+    @ApiOperation(value = "\u83b7\u53d6\u9910\u5385\u7b80\u8981\u4fe1\u606f", notes = "\u3010\u4ec5\u9650\u5185\u90e8Feign\u8c03\u7528\u3011\u4f9b\u4ea7\u54c1\u670d\u52a1\u83b7\u53d6\u5355\u4e2a\u9910\u5385\u7684\u7b80\u8981\u4fe1\u606f\uff0c\u8fd4\u56deID\u3001\u540d\u79f0\u3001\u5206\u7c7b\u7f16\u7801\u3001\u57ce\u5e02\u3001\u72b6\u6001\u3002\u4e0d\u5b58\u5728\u65f6\u8fd4\u56de\u9519\u8bef\u3002\n\n**\u5173\u8054\u5b57\u5178**\uff1a\n- restaurant_category\uff08\u9910\u5385\u5206\u7c7b\uff0c\u8fd4\u56de\u5b57\u6bb5categoryCode\uff09\uff1aCHINESE=\u4e2d\u9910, WESTERN=\u897f\u9910, BBQ=\u70e7\u70e4, HOTPOT=\u706b\u9505, LOCAL=\u5f53\u5730\u7279\u8272\n- common_status\uff08\u72b6\u6001\uff0c\u8fd4\u56de\u5b57\u6bb5status\uff09\uff1aACTIVE=\u542f\u7528, INACTIVE=\u505c\u7528")
     @GetMapping("/item/{restaurantId}")
     public Result<Map<String, Object>> getRestaurantBrief(@PathVariable Long restaurantId) {
         Restaurant restaurant = restaurantService.getRestaurantEntity(restaurantId);
@@ -41,7 +41,7 @@ public class InternalRestaurantController {
         return Result.success(brief);
     }
 
-    @ApiOperation("\u6279\u91cf\u83b7\u53d6\u9910\u5385\u7b80\u8981\u4fe1\u606f")
+    @ApiOperation(value = "\u6279\u91cf\u83b7\u53d6\u9910\u5385\u7b80\u8981\u4fe1\u606f", notes = "\u3010\u4ec5\u9650\u5185\u90e8Feign\u8c03\u7528\u3011\u6279\u91cf\u83b7\u53d6\u9910\u5385\u7b80\u8981\u4fe1\u606f\uff0c\u6700\u591a500\u4e2aID\u3002\u4e0d\u5b58\u5728\u7684ID\u81ea\u52a8\u8fc7\u6ee4\u3002\u4f9b\u4ea7\u54c1\u670d\u52a1\u6279\u91cf\u67e5\u8be2\u884c\u7a0b\u8282\u70b9\u7ed1\u5b9a\u7684\u9910\u5385\u8d44\u6e90\u3002\n\n**\u5173\u8054\u5b57\u5178**\uff1a\n- restaurant_category\uff08\u9910\u5385\u5206\u7c7b\uff0c\u8fd4\u56de\u5b57\u6bb5categoryCode\uff09\uff1aCHINESE=\u4e2d\u9910, WESTERN=\u897f\u9910, BBQ=\u70e7\u70e4, HOTPOT=\u706b\u9505, LOCAL=\u5f53\u5730\u7279\u8272\n- common_status\uff08\u72b6\u6001\uff0c\u8fd4\u56de\u5b57\u6bb5status\uff09\uff1aACTIVE=\u542f\u7528, INACTIVE=\u505c\u7528")
     @GetMapping("/items/batch")
     public Result<List<Map<String, Object>>> getRestaurantsBatch(@RequestParam @Size(max = 500) List<Long> restaurantIds) {
         List<Map<String, Object>> results = restaurantIds.stream()
@@ -61,9 +61,9 @@ public class InternalRestaurantController {
         return Result.success(results);
     }
 
-    @ApiOperation("\u5904\u7406\u5ba1\u6279\u56de\u8c03\u7ed3\u679c")
+    @ApiOperation(value = "\u5904\u7406\u5ba1\u6279\u56de\u8c03\u7ed3\u679c", notes = "\u3010\u4ec5\u9650\u5185\u90e8Feign\u8c03\u7528\u3011\u63a5\u6536\u4f01\u5faeOA\u5ba1\u6279\u56de\u8c03\uff0c\u6309thirdNo\u5339\u914d\u9910\u5385\u5e76\u66f4\u65b0\u542f\u7528/\u7981\u7528\u72b6\u6001\u3002\u7531hl-callback-service\u901a\u8fc7MQ\u6d88\u8d39\u540e\u8c03\u7528\uff0c\u5e42\u7b49\u5904\u7406\u3002\n\n**\u5173\u8054\u5b57\u5178**\uff1a\n- approval_sp_status\uff08\u5ba1\u6279\u72b6\u6001\uff0c\u8bf7\u6c42\u5b57\u6bb5spStatus\uff09")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         restaurantService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java
index eb8164c..7c8961f 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java
@@ -26,7 +26,7 @@ public class RestaurantController {
 
     private final RestaurantService restaurantService;
 
-    @ApiOperation("创建餐厅")
+    @ApiOperation(value = "创建餐厅", notes = "新建餐厅资源，初始状态为草稿(status=0)。餐厅没有价格日历，费用通过产品报价中的费用项管理。需走企微审批流程上架。\n\n**关联字典**：\n- restaurant_category：餐厅分类（表单选择）\n- cuisine_type：菜系类型（表单多选）\n- environment_type：环境类型（表单多选）\n- restaurant_facility：餐厅设施（表单多选）\n\n**纯文本字段**：\n- cityName：城市名称（手动输入，如「拉萨」「海拉尔」）")
     @PostMapping("/item")
     public Result<RestaurantVO> createRestaurant(
             @ApiParam("餐厅创建请求") @Valid @RequestBody RestaurantCreateRequest request,
@@ -35,19 +35,19 @@ public class RestaurantController {
         return Result.success(restaurantService.createRestaurant(request, adminId));
     }
 
-    @ApiOperation("餐厅列表")
+    @ApiOperation(value = "餐厅列表", notes = "分页查询餐厅列表，支持按名称、状态、分类、城市等条件筛选。\n\n**关联字典**：\n- restaurant_category：餐厅分类（筛选+列表显示）\n- cuisine_type：菜系类型（列表显示）\n- environment_type：环境类型（列表显示）\n- restaurant_facility：餐厅设施（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<RestaurantListVO>> listRestaurants(@ApiParam("餐厅查询请求") @Valid RestaurantQueryRequest query) {
         return Result.success(restaurantService.listRestaurants(query));
     }
 
-    @ApiOperation("餐厅详情")
+    @ApiOperation(value = "餐厅详情", notes = "获取餐厅完整信息，包含素材URL、标签、富文本介绍等。\n\n**关联字典**：\n- restaurant_category：餐厅分类（详情显示）\n- cuisine_type：菜系类型（详情显示）\n- environment_type：环境类型（详情显示）\n- restaurant_facility：餐厅设施（详情显示）")
     @GetMapping("/item/{restaurantId}")
     public Result<RestaurantVO> getRestaurant(@ApiParam("餐厅ID") @PathVariable Long restaurantId) {
         return Result.success(restaurantService.getRestaurant(restaurantId));
     }
 
-    @ApiOperation("更新餐厅")
+    @ApiOperation(value = "更新餐厅", notes = "更新餐厅基本信息，不改变当前状态。\n\n**关联字典**：\n- restaurant_category：餐厅分类（表单选择）\n- cuisine_type：菜系类型（表单多选）\n- environment_type：环境类型（表单多选）\n- restaurant_facility：餐厅设施（表单多选）\n\n**纯文本字段**：\n- cityName：城市名称（手动输入）")
     @PutMapping("/item/{restaurantId}")
     public Result<RestaurantVO> updateRestaurant(
             @ApiParam("餐厅ID") @PathVariable Long restaurantId,
@@ -57,7 +57,7 @@ public class RestaurantController {
         return Result.success(restaurantService.updateRestaurant(restaurantId, request, adminId));
     }
 
-    @ApiOperation("删除餐厅")
+    @ApiOperation(value = "删除餐厅", notes = "软删除餐厅。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/item/{restaurantId}")
     public Result<Void> deleteRestaurant(
             @ApiParam("餐厅ID") @PathVariable Long restaurantId,
@@ -68,7 +68,7 @@ public class RestaurantController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。")
     @PostMapping("/item/{restaurantId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("餐厅ID") @PathVariable Long restaurantId,
@@ -80,7 +80,7 @@ public class RestaurantController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("上下架切换")
+    @ApiOperation(value = "上下架切换", notes = "直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/item/{restaurantId}/status")
     public Result<Void> updateStatus(
             @ApiParam("餐厅ID") @PathVariable Long restaurantId,
@@ -91,7 +91,7 @@ public class RestaurantController {
         return Result.success();
     }
 
-    @ApiOperation("批量上下架")
+    @ApiOperation(value = "批量上下架", notes = "批量修改多个餐厅的状态，跳过审批流程。")
     @PutMapping("/items/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("餐厅状态请求") @Valid @RequestBody RestaurantStatusRequest request,
@@ -103,7 +103,7 @@ public class RestaurantController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个餐厅。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/items/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java
index 05b1056..7f96d5a 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantTagController.java
@@ -27,7 +27,7 @@ public class RestaurantTagController {
 
     private final RestaurantTagService tagService;
 
-    @ApiOperation("\u83b7\u53d6\u7ba1\u7406\u6807\u7b7e\u5217\u8868\uff08\u5206\u9875\uff09")
+    @ApiOperation(value = "\u83b7\u53d6\u7ba1\u7406\u6807\u7b7e\u5217\u8868\uff08\u5206\u9875\uff09", notes = "\u5206\u9875\u67e5\u8be2\u9910\u5385\u6807\u7b7e\u5e93\uff0c\u652f\u6301\u6309\u5173\u952e\u8bcd\u641c\u7d22\u3002\u5305\u542b\u9884\u8bbe\u6807\u7b7e\u548c\u81ea\u5b9a\u4e49\u6807\u7b7e\u3002")
     @GetMapping("/tags")
     public Result<PageResult<RestaurantTagVO>> listManagedTags(
             @ApiParam("\u9875\u7801") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class RestaurantTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("\u83b7\u53d6\u5168\u90e8\u6807\u7b7e")
+    @ApiOperation(value = "\u83b7\u53d6\u5168\u90e8\u6807\u7b7e", notes = "\u4e0d\u5206\u9875\u8fd4\u56de\u6240\u6709\u6807\u7b7e\uff0c\u7528\u4e8e\u9910\u5385\u7f16\u8f91\u65f6\u7684\u6807\u7b7e\u9009\u62e9\u4e0b\u62c9\u3002")
     @GetMapping("/tags/all")
     public Result<List<RestaurantTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("\u521b\u5efa\u7ba1\u7406\u6807\u7b7e")
+    @ApiOperation(value = "\u521b\u5efa\u7ba1\u7406\u6807\u7b7e", notes = "\u521b\u5efa\u9884\u8bbe\u6807\u7b7e\uff0c\u6807\u7b7e\u540d\u4e0d\u53ef\u91cd\u590d\u3002\u53ef\u6307\u5b9a\u989c\u8272(tagColor)\uff0c\u9ed8\u8ba4#409EFF\u3002")
     @PostMapping("/tag")
     public Result<RestaurantTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class RestaurantTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("\u89e3\u6790\u81ea\u5b9a\u4e49\u6807\u7b7e")
+    @ApiOperation(value = "\u89e3\u6790\u81ea\u5b9a\u4e49\u6807\u7b7e", notes = "\u6309\u540d\u79f0\u67e5\u627e\u6216\u81ea\u52a8\u521b\u5efa\u6807\u7b7e\u3002\u7528\u4e8e\u9910\u5385\u7f16\u8f91\u65f6\u5feb\u901f\u8f93\u5165\u65b0\u6807\u7b7e\u3002")
     @PostMapping("/tag/adhoc")
     public Result<RestaurantTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class RestaurantTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("\u7f16\u8f91\u6807\u7b7e")
+    @ApiOperation(value = "\u7f16\u8f91\u6807\u7b7e", notes = "\u4fee\u6539\u6807\u7b7e\u540d\u79f0\u6216\u989c\u8272\uff0c\u6240\u6709\u5173\u8054\u9910\u5385\u81ea\u52a8\u751f\u6548\u3002")
     @PutMapping("/tag/{tagId}")
     public Result<RestaurantTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class RestaurantTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("\u5220\u9664\u6807\u7b7e")
+    @ApiOperation(value = "\u5220\u9664\u6807\u7b7e", notes = "\u5220\u9664\u6807\u7b7e\u5e76\u89e3\u9664\u6240\u6709\u9910\u5385\u4e0e\u8be5\u6807\u7b7e\u7684\u5173\u8054\u3002")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("\u66f4\u65b0\u9910\u5385\u6807\u7b7e")
+    @ApiOperation(value = "\u66f4\u65b0\u9910\u5385\u6807\u7b7e", notes = "\u5168\u91cf\u66ff\u6362\u6307\u5b9a\u9910\u5385\u7684\u6807\u7b7e\u5217\u8868\u3002\u4f20\u5165tagIds\u4e3a\u6700\u7ec8\u5173\u8054\u7684\u6807\u7b7eID\u5217\u8868\uff0c\u4e3a\u7a7a\u5219\u6e05\u9664\u6240\u6709\u6807\u7b7e\u3002")
     @PutMapping("/item/{restaurantId}/tags")
     public Result<Void> updateRestaurantTags(
             @ApiParam("餐厅ID") @PathVariable Long restaurantId,
@@ -87,7 +87,7 @@ public class RestaurantTagController {
         return Result.success();
     }
 
-    @ApiOperation("\u6279\u91cf\u6253\u6807\u7b7e")
+    @ApiOperation(value = "\u6279\u91cf\u6253\u6807\u7b7e", notes = "\u5bf9\u591a\u4e2a\u9910\u5385\u6279\u91cf\u6dfb\u52a0/\u79fb\u9664\u6807\u7b7e\u3002\u589e\u91cf\u64cd\u4f5c\uff0c\u4e0d\u5f71\u54cd\u672a\u6307\u5b9a\u7684\u6807\u7b7e\u3002")
     @PutMapping("/items/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java
index 629213d..23de858 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java
@@ -61,8 +61,8 @@ public class RestaurantCreateRequest {
     @Size(max = 30)
     private String district;
 
-    @ApiModelProperty(value = "城市标签", required = true, example = "拉萨")
-    @NotBlank(message = "城市标签不能为空")
+    @ApiModelProperty(value = "城市名称（纯文本输入）", required = true, example = "拉萨")
+    @NotBlank(message = "城市名称不能为空")
     @Size(max = 30)
     private String cityName;

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java
index 34e331b..ba2f6e9 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java
@@ -25,7 +25,7 @@ public class RestaurantQueryRequest {
     @ApiModelProperty(value = "省份", example = "西藏自治区")
     private String province;
 
-    @ApiModelProperty(value = "城市标签", example = "拉萨")
+    @ApiModelProperty(value = "城市名称筛选（纯文本）", example = "拉萨")
     private String cityName;
 
     @ApiModelProperty(value = "城市", example = "拉萨市")

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java
index 8b62d81..51eb13c 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java
@@ -57,7 +57,7 @@ public class RestaurantUpdateRequest {
     @Size(max = 30)
     private String district;
 
-    @ApiModelProperty(value = "城市标签", example = "拉萨")
+    @ApiModelProperty(value = "城市名称（纯文本输入）", example = "拉萨")
     @Size(max = 30)
     private String cityName;

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java
index df37c80..f0d4d24 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java
@@ -36,7 +36,7 @@ public class RestaurantListVO {
     @ApiModelProperty("人均消费（元）")
     private BigDecimal pricePerPerson;
 
-    @ApiModelProperty("城市标签")
+    @ApiModelProperty("城市名称（纯文本）")
     private String cityName;
 
     @ApiModelProperty("亮点摘要")

`hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java
index acfd3d8..4396d6e 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java
@@ -54,7 +54,7 @@ public class RestaurantVO {
     @ApiModelProperty("区县")
     private String district;
 
-    @ApiModelProperty("城市标签")
+    @ApiModelProperty("城市名称（纯文本）")
     private String cityName;
 
     @ApiModelProperty("详细地址")

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java
index dbe9f19..a28ef38 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalMpScenicController.java
@@ -17,7 +17,7 @@ import java.util.List;
 /**
  * C端景区内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  */
-@Api(tags = "【内部接口】小程序景区（Feign调用）")
+@Api(tags = "【内部接口】小程序景区（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/scenic")
 @RequiredArgsConstructor
@@ -25,21 +25,21 @@ public class InternalMpScenicController {
 
     private final ScenicSpotService scenicSpotService;
 
-    @ApiOperation("C端景区列表")
+    @ApiOperation(value = "C端景区列表", notes = "【仅限内部Feign调用】供mp-service BFF聚合使用。强制status=1只返回已上架景区，支持分页、城市筛选和关键词搜索。C端用户通过小程序间接访问。\n\ncityName为纯文本筛选字段，非字典。")
     @GetMapping("/list")
     public Result<PageResult<ScenicSpotListVO>> listScenic(ScenicSpotQueryRequest query) {
         query.setStatus(1);
         return Result.success(scenicSpotService.listSpots(query));
     }
 
-    @ApiOperation("C端景区详情")
+    @ApiOperation(value = "C端景区详情", notes = "【仅限内部Feign调用】供mp-service获取景区完整详情，包含封面、轮播图、标签、季节内容、富文本介绍、坐标等。注意：不限制status，由BFF层校验是否展示。")
     @GetMapping("/{scenicId}")
     public Result<ScenicSpotVO> getScenicDetail(@PathVariable Long scenicId) {
         ScenicSpotVO vo = scenicSpotService.getSpot(scenicId);
         return Result.success(vo);
     }
 
-    @ApiOperation("C端附近景区")
+    @ApiOperation(value = "C端附近景区", notes = "【仅限内部Feign调用】根据指定景区的坐标查询附近的景区列表。radius为搜索半径(km,默认50)，limit为最大返回数(默认10)。按距离排序，返回名称、封面、距离等信息。")
     @GetMapping("/{scenicId}/nearby")
     public Result<List<NearbyScenicVO>> getNearbyScenic(
             @PathVariable Long scenicId,

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java
index a902ee1..9f47695 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/InternalScenicController.java
@@ -22,7 +22,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】景区（Feign调用）")
+@Api(tags = "【内部接口】景区（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/scenic")
 @RequiredArgsConstructor
@@ -31,7 +31,7 @@ public class InternalScenicController {
     private final ScenicSpotService spotService;
     private final ScenicPriceCalendarService priceService;
 
-    @ApiOperation("获取景区简要信息")
+    @ApiOperation(value = "获取景区简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个景区的简要信息，返回ID、名称、荣誉称号、城市、状态。不存在时返回错误。\n\n**关联字典**：\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/spot/{scenicId}")
     public Result<Map<String, Object>> getSpotBrief(@PathVariable Long scenicId) {
         ScenicSpot spot = spotService.getSpotEntity(scenicId);
@@ -47,7 +47,7 @@ public class InternalScenicController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取景区简要信息")
+    @ApiOperation(value = "批量获取景区简要信息", notes = "【仅限内部Feign调用】批量获取景区简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询行程节点绑定的景区资源。\n\n**关联字典**：\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/spots/batch")
     public Result<List<Map<String, Object>>> getSpotsBatch(@RequestParam @Size(max = 500) List<Long> scenicIds) {
         List<Map<String, Object>> results = scenicIds.stream()
@@ -67,7 +67,7 @@ public class InternalScenicController {
         return Result.success(results);
     }
 
-    @ApiOperation("查询某日价格")
+    @ApiOperation(value = "查询某日价格", notes = "【仅限内部Feign调用】查询景区指定日期的价格日历信息，包含成本价、售价、库存、状态。date格式为yyyy-MM-dd。供产品服务报价计算和库存校验使用。")
     @GetMapping("/spot/{scenicId}/price/{date}")
     public Result<PriceCalendarDayVO> getPriceForDate(
             @PathVariable Long scenicId,
@@ -76,7 +76,7 @@ public class InternalScenicController {
         return Result.success(price);
     }
 
-    @ApiOperation("判断某日是否可售")
+    @ApiOperation(value = "判断某日是否可售", notes = "【仅限内部Feign调用】判断景区指定日期是否可售（价格日历存在且状态为启用且库存>0）。供订单服务下单前校验使用。")
     @GetMapping("/spot/{scenicId}/available/{date}")
     public Result<Boolean> isAvailable(
             @PathVariable Long scenicId,
@@ -84,7 +84,7 @@ public class InternalScenicController {
         return Result.success(priceService.isAvailable(scenicId, LocalDate.parse(date)));
     }
 
-    @ApiOperation("扣减库存")
+    @ApiOperation(value = "扣减库存", notes = "【仅限内部Feign调用】扣减景区指定日期的库存数量。下单成功时由订单服务调用。库存不足时返回false。使用乐观锁防止超卖。")
     @PutMapping("/spot/{scenicId}/stock/deduct")
     public Result<Boolean> deductStock(
             @PathVariable Long scenicId,
@@ -94,7 +94,7 @@ public class InternalScenicController {
         return Result.success(success);
     }
 
-    @ApiOperation("恢复库存")
+    @ApiOperation(value = "恢复库存", notes = "【仅限内部Feign调用】恢复景区指定日期的库存数量。订单取消或退款时由订单服务调用，将之前扣减的库存加回。")
     @PutMapping("/spot/{scenicId}/stock/restore")
     public Result<Void> restoreStock(
             @PathVariable Long scenicId,
@@ -104,9 +104,9 @@ public class InternalScenicController {
         return Result.success();
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配景区并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         spotService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java
index 8e2b1cb..62d7de0 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarController.java
@@ -25,7 +25,7 @@ public class ScenicPriceCalendarController {
 
     private final ScenicPriceCalendarService priceService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询景区的每日价格和可售状态。返回指定年月中所有已设置价格的日期，未设置的日期不返回。用于前端日历组件渲染。")
     @GetMapping("/spot/{scenicId}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -34,7 +34,7 @@ public class ScenicPriceCalendarController {
         return Result.success(priceService.getPriceCalendar(scenicId, year, month));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格", notes = "在指定日期范围内批量设置成本价、库存和可售状态。支持weekdayOnly/weekendOnly/selectedWeekdays过滤特定星期，支持excludeDates排除特定日期。已有价格的日期会被覆盖更新。")
     @PutMapping("/spot/{scenicId}/prices")
     public Result<Void> batchSetPrices(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -43,7 +43,7 @@ public class ScenicPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改可售状态")
+    @ApiOperation(value = "批量修改可售状态", notes = "批量修改指定日期范围内的可售状态，不影响价格和库存。status=0不可售，status=1可售。用于临时关闭/开放某些日期的售卖。")
     @PutMapping("/spot/{scenicId}/prices/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -52,7 +52,7 @@ public class ScenicPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量清除价格")
+    @ApiOperation(value = "批量清除价格", notes = "删除指定日期范围内的所有价格记录。删除后该日期范围将显示为未设置状态。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/spot/{scenicId}/prices")
     public Result<Void> deletePrices(
             @ApiParam("景区ID") @PathVariable Long scenicId,

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java
index 8933ec2..ab7ad78 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSeasonController.java
@@ -22,13 +22,13 @@ public class ScenicSeasonController {
 
     private final ScenicSeasonService seasonService;
 
-    @ApiOperation("获取景区全部季节内容")
+    @ApiOperation(value = "获取景区全部季节内容", notes = "返回景区的所有季节内容列表（春/夏/秋/冬）。季节内容是景区独有功能，其他资源类型没有此概念。每个季节可设置独立的封面、轮播图、亮点描述和游玩攻略。")
     @GetMapping("/spot/{scenicId}/seasons")
     public Result<List<ScenicSeasonVO>> getSeasons(@ApiParam("景区ID") @PathVariable Long scenicId) {
         return Result.success(seasonService.getSeasons(scenicId));
     }
 
-    @ApiOperation("保存/更新季节内容")
+    @ApiOperation(value = "保存/更新季节内容", notes = "创建或更新指定景区的季节内容。seasonType为季节标识（如spring/summer/autumn/winter）。如果该季节已存在则更新，不存在则创建。支持设置季节别名（如「樱花季」）、月份范围、独立封面和轮播图。")
     @PutMapping("/spot/{scenicId}/season/{seasonType}")
     public Result<ScenicSeasonVO> saveSeason(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -39,7 +39,7 @@ public class ScenicSeasonController {
         return Result.success(seasonService.saveSeason(scenicId, seasonType, request, adminId));
     }
 
-    @ApiOperation("删除季节内容")
+    @ApiOperation(value = "删除季节内容", notes = "删除指定景区的某个季节内容，同时清理关联的素材引用。")
     @DeleteMapping("/spot/{scenicId}/season/{seasonType}")
     public Result<Void> deleteSeason(
             @ApiParam("景区ID") @PathVariable Long scenicId,

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java
index b8aff01..c2da355 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java
@@ -26,7 +26,7 @@ public class ScenicSpotController {
 
     private final ScenicSpotService spotService;
 
-    @ApiOperation("创建景区")
+    @ApiOperation(value = "创建景区", notes = "新建一个景区资源，初始状态为草稿(status=0)。创建后需通过「提交启用审批」接口走企微OA审批流程才能上架。支持富文本字段（featureIntro/detailContent等），素材ID从素材库获取。\n\n**关联字典**：\n- scenic_facility：景区设施（表单多选）\n- scenic_honor：景区荣誉（表单多选）")
     @PostMapping("/spot")
     public Result<ScenicSpotVO> createSpot(
             @ApiParam("景区创建请求") @Valid @RequestBody ScenicSpotCreateRequest request,
@@ -35,19 +35,19 @@ public class ScenicSpotController {
         return Result.success(spotService.createSpot(request, adminId));
     }
 
-    @ApiOperation("景区列表")
+    @ApiOperation(value = "景区列表", notes = "分页查询景区列表，支持按名称关键词、状态(0草稿/1上架/2下架)、城市等条件筛选。返回列表摘要信息（不含富文本详情），按sortOrder倒序+创建时间倒序排列。\n\n**关联字典**：\n- scenic_facility：景区设施（列表显示）\n- scenic_honor：景区荣誉（列表显示）")
     @GetMapping("/spots")
     public Result<PageResult<ScenicSpotListVO>> listSpots(@ApiParam("景区查询请求") @Valid ScenicSpotQueryRequest query) {
         return Result.success(spotService.listSpots(query));
     }
 
-    @ApiOperation("景区详情")
+    @ApiOperation(value = "景区详情", notes = "获取景区完整信息，包含富文本内容、素材URL、标签列表、季节内容等。素材ID会自动解析为OSS访问地址。\n\n**关联字典**：\n- scenic_facility：景区设施（详情显示）\n- scenic_honor：景区荣誉（详情显示）")
     @GetMapping("/spot/{scenicId}")
     public Result<ScenicSpotVO> getSpot(@ApiParam("景区ID") @PathVariable Long scenicId) {
         return Result.success(spotService.getSpot(scenicId));
     }
 
-    @ApiOperation("更新景区")
+    @ApiOperation(value = "更新景区", notes = "更新景区基本信息和富文本内容。更新不会改变当前状态。如果景区已上架，修改后仍保持上架状态，无需重新审批。\n\n**关联字典**：\n- scenic_facility：景区设施（表单多选）\n- scenic_honor：景区荣誉（表单多选）")
     @PutMapping("/spot/{scenicId}")
     public Result<ScenicSpotVO> updateSpot(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -57,7 +57,7 @@ public class ScenicSpotController {
         return Result.success(spotService.updateSpot(scenicId, request, adminId));
     }
 
-    @ApiOperation("删除景区")
+    @ApiOperation(value = "删除景区", notes = "软删除景区（设置deleted_at）。仅SUPER_ADMIN角色或创建者本人可删除。已上架的景区需先下架再删除。删除后会同时清理关联的素材引用。")
     @DeleteMapping("/spot/{scenicId}")
     public Result<Void> deleteSpot(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -68,7 +68,7 @@ public class ScenicSpotController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交审批申请。targetStatus=1表示申请上架，targetStatus=2表示申请下架。提交后景区进入PENDING_APPROVAL状态，企微审批通过/拒绝后通过回调自动更新状态。返回企微审批单号spNo。同一景区不可重复提交未完成的审批。")
     @PostMapping("/spot/{scenicId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -80,7 +80,7 @@ public class ScenicSpotController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("上下架切换")
+    @ApiOperation(value = "上下架切换", notes = "直接修改景区状态（跳过审批流程），仅限SUPER_ADMIN使用。普通管理员应使用「提交启用/禁用审批」接口。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/spot/{scenicId}/status")
     public Result<Void> updateStatus(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -91,7 +91,7 @@ public class ScenicSpotController {
         return Result.success();
     }
 
-    @ApiOperation("批量上下架")
+    @ApiOperation(value = "批量上下架", notes = "批量修改多个景区的状态。scenicIds为景区ID列表（字符串格式），status为目标状态。跳过审批流程，适用于批量管理场景。")
     @PutMapping("/spots/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("景区状态请求") @Valid @RequestBody ScenicStatusRequest request,
@@ -103,7 +103,7 @@ public class ScenicSpotController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个景区。权限校验同单个删除：仅SUPER_ADMIN或创建者可操作。部分失败不影响其他景区的删除。")
     @DeleteMapping("/spots/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java
index eda0e91..1410edc 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicTagController.java
@@ -27,7 +27,7 @@ public class ScenicTagController {
 
     private final ScenicTagService tagService;
 
-    @ApiOperation("获取管理标签列表（分页）")
+    @ApiOperation(value = "获取管理标签列表（分页）", notes = "分页查询景区标签库中的所有标签，支持按关键词搜索。标签分为预设标签（管理员创建）和自定义标签（adhoc接口创建），此接口返回全部类型。")
     @GetMapping("/tags")
     public Result<PageResult<ScenicTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class ScenicTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("获取全部标签")
+    @ApiOperation(value = "获取全部标签", notes = "不分页返回所有标签，用于景区编辑时的标签选择下拉列表。")
     @GetMapping("/tags/all")
     public Result<List<ScenicTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建管理标签")
+    @ApiOperation(value = "创建管理标签", notes = "创建预设标签，标签名不可重复。可指定颜色(tagColor)，默认为#409EFF。预设标签在标签管理页面展示和维护。")
     @PostMapping("/tag")
     public Result<ScenicTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class ScenicTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "输入标签名称，如果已存在则直接返回，不存在则自动创建。用于景区编辑时快速输入新标签，避免先到标签管理页面创建。")
     @PostMapping("/tag/adhoc")
     public Result<ScenicTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class ScenicTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("编辑标签")
+    @ApiOperation(value = "编辑标签", notes = "修改标签名称或颜色。修改后所有关联此标签的景区会自动生效。")
     @PutMapping("/tag/{tagId}")
     public Result<ScenicTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class ScenicTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并自动解除所有景区与该标签的关联关系。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("更新景区标签")
+    @ApiOperation(value = "更新景区标签", notes = "全量替换指定景区的标签列表。传入tagIds为该景区最终要关联的标签ID列表，为空则清除所有标签。")
     @PutMapping("/spot/{scenicId}/tags")
     public Result<Void> updateScenicTags(
             @ApiParam("景区ID") @PathVariable Long scenicId,
@@ -87,7 +87,7 @@ public class ScenicTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量打标签")
+    @ApiOperation(value = "批量打标签", notes = "对多个景区批量添加或移除标签。addTagIds为要添加的标签，removeTagIds为要移除的标签，两者可同时使用。增量操作，不影响未指定的标签。")
     @PutMapping("/spots/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {

`hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java
index 95c02bf..4125c0d 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/InternalServiceController.java
@@ -17,7 +17,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】增值服务（Feign调用）")
+@Api(tags = "【内部接口】增值服务（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/service")
 @RequiredArgsConstructor
@@ -25,7 +25,7 @@ public class InternalServiceController {
 
     private final ServiceItemService serviceItemService;
 
-    @ApiOperation("获取服务简要信息")
+    @ApiOperation(value = "获取服务简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个增值服务的简要信息，返回ID、名称、分类编码、计费类型、是否收费、状态。不存在时返回错误。\n\n**关联字典**：\n- service_unit（计费单位，返回字段billingType）：PER_PERSON=元/人, PER_TIME=元/次, PER_DAY=元/天, PER_VEHICLE=元/台, FIXED=固定金额\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/item/{serviceId}")
     public Result<Map<String, Object>> getServiceBrief(@PathVariable Long serviceId) {
         ServiceItem item = serviceItemService.getServiceItemEntity(serviceId);
@@ -42,7 +42,7 @@ public class InternalServiceController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取服务简要信息")
+    @ApiOperation(value = "批量获取服务简要信息", notes = "【仅限内部Feign调用】批量获取增值服务简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询产品关联的服务项。\n\n**关联字典**：\n- service_unit（计费单位，返回字段billingType）：PER_PERSON=元/人, PER_TIME=元/次, PER_DAY=元/天, PER_VEHICLE=元/台, FIXED=固定金额\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/items/batch")
     public Result<List<Map<String, Object>>> getServiceBatch(@RequestParam @Size(max = 500) List<Long> serviceIds) {
         List<Map<String, Object>> results = serviceIds.stream()
@@ -63,9 +63,9 @@ public class InternalServiceController {
         return Result.success(results);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配增值服务并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         serviceItemService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java
index 6750979..52e1bb9 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java
@@ -26,7 +26,7 @@ public class ServiceItemController {
 
     private final ServiceItemService serviceItemService;
 
-    @ApiOperation("创建服务")
+    @ApiOperation(value = "创建增值服务", notes = "新建增值服务项目（如保险、签证代办、接送机等），初始状态为草稿(status=0)。支持免费(isPaid=false)和付费两种模式，付费服务有独立的价格日历。需走企微审批上架。\n\n**关联字典**：\n- service_category：服务分类（表单选择）\n- billing_type_service：服务计费方式（表单选择）\n- service_unit：服务计量单位（表单选择）")
     @PostMapping("/item")
     public Result<ServiceItemVO> createServiceItem(
             @ApiParam("服务创建请求") @Valid @RequestBody ServiceCreateRequest request,
@@ -35,19 +35,19 @@ public class ServiceItemController {
         return Result.success(serviceItemService.createServiceItem(request, adminId));
     }
 
-    @ApiOperation("服务列表")
+    @ApiOperation(value = "增值服务列表", notes = "分页查询增值服务列表，支持按名称、状态、分类等条件筛选。\n\n**关联字典**：\n- service_category：服务分类（筛选+列表显示）\n- billing_type_service：服务计费方式（列表显示）\n- service_unit：服务计量单位（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<ServiceItemListVO>> listServiceItems(@ApiParam("服务查询请求") @Valid ServiceQueryRequest query) {
         return Result.success(serviceItemService.listServiceItems(query));
     }
 
-    @ApiOperation("服务详情")
+    @ApiOperation(value = "增值服务详情", notes = "获取增值服务完整信息，包含素材URL、标签、计费方式等。\n\n**关联字典**：\n- service_category：服务分类（详情显示）\n- billing_type_service：服务计费方式（详情显示）\n- service_unit：服务计量单位（详情显示）")
     @GetMapping("/item/{serviceId}")
     public Result<ServiceItemVO> getServiceItem(@ApiParam("服务ID") @PathVariable Long serviceId) {
         return Result.success(serviceItemService.getServiceItem(serviceId));
     }
 
-    @ApiOperation("更新服务")
+    @ApiOperation(value = "更新增值服务", notes = "更新增值服务基本信息，不改变当前状态。\n\n**关联字典**：\n- service_category：服务分类（表单选择）\n- billing_type_service：服务计费方式（表单选择）\n- service_unit：服务计量单位（表单选择）")
     @PutMapping("/item/{serviceId}")
     public Result<ServiceItemVO> updateServiceItem(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -57,7 +57,7 @@ public class ServiceItemController {
         return Result.success(serviceItemService.updateServiceItem(serviceId, request, adminId));
     }
 
-    @ApiOperation("删除服务")
+    @ApiOperation(value = "删除增值服务", notes = "软删除增值服务。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/item/{serviceId}")
     public Result<Void> deleteServiceItem(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -68,7 +68,7 @@ public class ServiceItemController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。")
     @PostMapping("/item/{serviceId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -80,7 +80,7 @@ public class ServiceItemController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("启用/禁用切换")
+    @ApiOperation(value = "启用/禁用切换", notes = "直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/item/{serviceId}/status")
     public Result<Void> updateStatus(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -91,7 +91,7 @@ public class ServiceItemController {
         return Result.success();
     }
 
-    @ApiOperation("批量启用/禁用")
+    @ApiOperation(value = "批量启用/禁用", notes = "批量修改多个增值服务的状态，跳过审批流程。")
     @PutMapping("/items/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("服务状态请求") @Valid @RequestBody ServiceStatusRequest request,
@@ -103,7 +103,7 @@ public class ServiceItemController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个增值服务。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/items/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java
index e96654d..a2f52d3 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServicePriceCalendarController.java
@@ -25,7 +25,7 @@ public class ServicePriceCalendarController {
 
     private final ServicePriceCalendarService priceService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询增值服务的每日价格和可售状态。仅付费服务(isPaid=true)需要设置价格日历。")
     @GetMapping("/item/{serviceId}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -34,7 +34,7 @@ public class ServicePriceCalendarController {
         return Result.success(priceService.getPriceCalendar(serviceId, year, month));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格", notes = "在指定日期范围内批量设置服务的成本价和可售状态。")
     @PutMapping("/item/{serviceId}/prices")
     public Result<Void> batchSetPrices(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -43,7 +43,7 @@ public class ServicePriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改可售状态")
+    @ApiOperation(value = "批量修改可售状态", notes = "批量修改日期范围内的可售状态，不影响价格。")
     @PutMapping("/item/{serviceId}/prices/batch-status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -52,7 +52,7 @@ public class ServicePriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量清除价格")
+    @ApiOperation(value = "批量清除价格", notes = "删除指定日期范围内的价格记录。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/item/{serviceId}/prices")
     public Result<Void> deletePrices(
             @ApiParam("服务ID") @PathVariable Long serviceId,

`hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java
index cf3865a..5dca328 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceTagController.java
@@ -27,7 +27,7 @@ public class ServiceTagController {
 
     private final ServiceTagService tagService;
 
-    @ApiOperation("获取管理标签列表（分页）")
+    @ApiOperation(value = "获取管理标签列表（分页）", notes = "分页查询增值服务标签库，支持按关键词搜索。")
     @GetMapping("/tags")
     public Result<PageResult<ServiceTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class ServiceTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("获取全部标签")
+    @ApiOperation(value = "获取全部标签", notes = "不分页返回所有标签，用于服务编辑时的标签选择。")
     @GetMapping("/tags/all")
     public Result<List<ServiceTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建管理标签")
+    @ApiOperation(value = "创建管理标签", notes = "创建预设标签，标签名不可重复。")
     @PostMapping("/tag")
     public Result<ServiceTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class ServiceTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "按名称查找或自动创建标签。")
     @PostMapping("/tag/adhoc")
     public Result<ServiceTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class ServiceTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("编辑标签")
+    @ApiOperation(value = "编辑标签", notes = "修改标签名称或颜色，所有关联服务自动生效。")
     @PutMapping("/tag/{tagId}")
     public Result<ServiceTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class ServiceTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并解除所有服务与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("更新服务标签")
+    @ApiOperation(value = "更新服务标签", notes = "全量替换指定服务的标签列表。")
     @PutMapping("/item/{serviceId}/tags")
     public Result<Void> updateServiceTags(
             @ApiParam("服务ID") @PathVariable Long serviceId,
@@ -87,7 +87,7 @@ public class ServiceTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量打标签")
+    @ApiOperation(value = "批量打标签", notes = "对多个服务批量添加/移除标签。增量操作。")
     @PutMapping("/items/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {

`hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java
index 7c8bb51..ce700da 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java
@@ -19,7 +19,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】服务人员（Feign调用）")
+@Api(tags = "【内部接口】服务人员（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/staff")
 @RequiredArgsConstructor
@@ -28,7 +28,7 @@ public class InternalStaffController {
     private final StaffService staffService;
     private final StaffMapper staffMapper;
 
-    @ApiOperation("获取人员简要信息")
+    @ApiOperation(value = "获取人员简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个服务人员的简要信息，返回ID、姓名、人员类型、手机号、状态。不存在时返回错误。\n\n**关联字典**：\n- staff_type（人员类型，返回字段staffType）：GUIDE=导游, DRIVER=司机, PHOTOGRAPHER=摄影师, CHEF=厨师\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/{staffId}")
     public Result<Map<String, Object>> getStaffBrief(@PathVariable Long staffId) {
         Staff staff = staffService.getStaffEntity(staffId);
@@ -44,7 +44,7 @@ public class InternalStaffController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取人员简要信息")
+    @ApiOperation(value = "批量获取人员简要信息", notes = "【仅限内部Feign调用】批量获取服务人员简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询团批关联的服务人员。\n\n**关联字典**：\n- staff_type（人员类型，返回字段staffType）：GUIDE=导游, DRIVER=司机, PHOTOGRAPHER=摄影师, CHEF=厨师\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/batch")
     public Result<List<Map<String, Object>>> getStaffBatch(@RequestParam @Size(max = 500) List<Long> staffIds) {
         List<Map<String, Object>> results = staffIds.stream()
@@ -64,7 +64,7 @@ public class InternalStaffController {
         return Result.success(results);
     }
 
-    @ApiOperation("按人员类型查询")
+    @ApiOperation(value = "按人员类型查询", notes = "【仅限内部Feign调用】按staffType查询第一个匹配的服务人员。staffType如：GUIDE(导游)、DRIVER(司机)、PHOTOGRAPHER(摄影师)等。未找到时返回null。\n\n**关联字典**：\n- staff_type（人员类型，请求参数+返回字段staffType）：GUIDE=导游, DRIVER=司机, PHOTOGRAPHER=摄影师, CHEF=厨师\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/by-type/{staffType}")
     public Result<Map<String, Object>> getStaffByType(@PathVariable String staffType) {
         Staff staff = staffService.getStaffByType(staffType);
@@ -80,9 +80,9 @@ public class InternalStaffController {
         return Result.success(brief);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配服务人员并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         staffService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();
@@ -91,7 +91,7 @@ public class InternalStaffController {
     /**
      * Batch get staff basic info by comma-separated IDs (for product-service batch staff snapshot).
      */
-    @ApiOperation("批量获取人员基本信息(逗号分隔ID)")
+    @ApiOperation(value = "批量获取人员基本信息(逗号分隔ID)", notes = "【仅限内部Feign调用】通过逗号分隔的ID字符串批量获取人员基本信息（含staffId、name、phone、staffType、coverMaterialId）。供产品服务团批人员快照使用。与/batch接口不同，此接口接收逗号分隔字符串而非数组。\n\n**关联字典**：\n- staff_type（人员类型，返回字段staffType）：GUIDE=导游, DRIVER=司机, PHOTOGRAPHER=摄影师, CHEF=厨师")
     @GetMapping("/batch-basic")
     public Result<List<Map<String, Object>>> batchGetStaffBasic(@RequestParam String staffIds) {
         List<Long> ids = Arrays.stream(staffIds.split(","))
@@ -122,7 +122,7 @@ public class InternalStaffController {
      * List available staff (status=1), optionally filter by staffType.
      * Used by admin batch staff selection dropdown.
      */
-    @ApiOperation("列出可用人员(用于下拉选择)")
+    @ApiOperation(value = "列出可用人员(用于下拉选择)", notes = "【仅限内部Feign调用】列出所有status=1的可用服务人员，可按staffType筛选。按sortOrder和staffId排序。供管理后台团批分配人员的下拉选择框使用。\n\n**关联字典**：\n- staff_type（人员类型，请求参数+返回字段staffType）：GUIDE=导游, DRIVER=司机, PHOTOGRAPHER=摄影师, CHEF=厨师")
     @GetMapping("/list-available")
     public Result<List<Map<String, Object>>> listAvailableStaff(
             @RequestParam(required = false) String staffType) {

`hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java
index f90638f..be01710 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java
@@ -24,7 +24,7 @@ public class StaffController {
 
     private final StaffService staffService;
 
-    @ApiOperation("创建服务人员")
+    @ApiOperation(value = "创建服务人员", notes = "新建服务人员（导游/领队/摄影师/助理等）。人员类型(staffType)决定了其在价格日历中的归类。需走企微审批上架后才能被产品引用。\n\n**关联字典**：\n- staff_type：人员类型（表单选择）\n- guide_level：导游等级（表单选择）\n- driver_license_type：驾照类型（表单选择）\n- language：语言能力（表单多选）\n- guide_specialty：导游专长（表单多选）\n- guide_service_area：服务区域（表单多选）")
     @PostMapping
     public Result<StaffVO> createStaff(@ApiParam("服务人员创建请求") @Valid @RequestBody StaffCreateRequest request,
                                         HttpServletRequest httpRequest) {
@@ -32,19 +32,19 @@ public class StaffController {
         return Result.success(staffService.createStaff(request, adminId));
     }
 
-    @ApiOperation("服务人员列表")
+    @ApiOperation(value = "服务人员列表", notes = "分页查询服务人员列表，支持按姓名、状态、人员类型等条件筛选。\n\n**关联字典**：\n- staff_type：人员类型（筛选+列表显示）\n- guide_level：导游等级（列表显示）\n- driver_license_type：驾照类型（列表显示）\n- language：语言能力（列表显示）\n- guide_specialty：导游专长（列表显示）\n- guide_service_area：服务区域（列表显示）")
     @GetMapping("/list")
     public Result<PageResult<StaffListVO>> listStaff(@ApiParam("服务人员查询请求") @Valid StaffQueryRequest query) {
         return Result.success(staffService.listStaff(query));
     }
 
-    @ApiOperation("服务人员详情")
+    @ApiOperation(value = "服务人员详情", notes = "获取服务人员完整信息，包含素材URL、标签、技能描述等。\n\n**关联字典**：\n- staff_type：人员类型（详情显示）\n- guide_level：导游等级（详情显示）\n- driver_license_type：驾照类型（详情显示）\n- language：语言能力（详情显示）\n- guide_specialty：导游专长（详情显示）\n- guide_service_area：服务区域（详情显示）")
     @GetMapping("/{staffId}")
     public Result<StaffVO> getStaff(@ApiParam("人员ID") @PathVariable Long staffId) {
         return Result.success(staffService.getStaff(staffId));
     }
 
-    @ApiOperation("更新服务人员")
+    @ApiOperation(value = "更新服务人员", notes = "更新服务人员基本信息，不改变当前状态。\n\n**关联字典**：\n- staff_type：人员类型（表单选择）\n- guide_level：导游等级（表单选择）\n- driver_license_type：驾照类型（表单选择）\n- language：语言能力（表单多选）\n- guide_specialty：导游专长（表单多选）\n- guide_service_area：服务区域（表单多选）")
     @PutMapping("/{staffId}")
     public Result<StaffVO> updateStaff(@ApiParam("人员ID") @PathVariable Long staffId,
                                         @ApiParam("服务人员更新请求") @Valid @RequestBody StaffUpdateRequest request,
@@ -53,7 +53,7 @@ public class StaffController {
         return Result.success(staffService.updateStaff(staffId, request, adminId));
     }
 
-    @ApiOperation("删除服务人员")
+    @ApiOperation(value = "删除服务人员", notes = "软删除服务人员。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/{staffId}")
     public Result<Void> deleteStaff(@ApiParam("人员ID") @PathVariable Long staffId, HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);
@@ -62,7 +62,7 @@ public class StaffController {
         return Result.success();
     }
 
-    @ApiOperation("提交审批")
+    @ApiOperation(value = "提交审批", notes = "向企微OA提交人员启用/禁用审批。targetStatus=1申请启用，targetStatus=2申请禁用。返回审批单号spNo。")
     @PostMapping("/{staffId}/submit-approval")
     public Result<Map<String, String>> submitApproval(@ApiParam("人员ID") @PathVariable Long staffId,
                                                        @ApiParam("审批提交请求体") @Valid @RequestBody ApprovalSubmitRequest request,
@@ -72,7 +72,7 @@ public class StaffController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("更新状态")
+    @ApiOperation(value = "更新状态", notes = "直接修改人员状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=启用，2=禁用。")
     @PutMapping("/{staffId}/status")
     public Result<Void> updateStatus(@ApiParam("人员ID") @PathVariable Long staffId,
                                       @ApiParam("状态请求体") @Valid @RequestBody StaffStatusRequest request,
@@ -82,14 +82,14 @@ public class StaffController {
         return Result.success();
     }
 
-    @ApiOperation("批量更新状态")
+    @ApiOperation(value = "批量更新状态", notes = "批量修改多个服务人员的状态，跳过审批流程。")
     @PutMapping("/batch/status")
     public Result<Void> batchUpdateStatus(@ApiParam("批量状态请求体") @Valid @RequestBody StaffStatusRequest request) {
         staffService.batchUpdateStatus(request.getStaffIds(), request.getStatus());
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个服务人员。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/batch")
     public Result<Void> batchDelete(@ApiParam("批量删除请求体") @Valid @RequestBody StaffBatchDeleteRequest request,
                                      HttpServletRequest httpRequest) {

`hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java
index 2993bef..a762de1 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffPriceCalendarController.java
@@ -27,7 +27,7 @@ public class StaffPriceCalendarController {
 
     private final StaffPriceCalendarService priceCalendarService;
 
-    @ApiOperation("查询价格日历（按人员类型）")
+    @ApiOperation(value = "查询价格日历（按人员类型）", notes = "按月查询指定人员类型的每日服务费用和可调度状态。注意：价格日历按人员类型维度管理，非按个人维度。同一类型的所有人员共享同一套价格。\n\n**关联字典**：\n- staff_type（人员类型）→ staffType路径参数")
     @GetMapping("/type/{staffType}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(
             @ApiParam("人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER") @PathVariable String staffType,
@@ -36,7 +36,7 @@ public class StaffPriceCalendarController {
         return Result.success(priceCalendarService.getPriceCalendar(staffType, year, month));
     }
 
-    @ApiOperation("批量设置价格（按人员类型）")
+    @ApiOperation(value = "批量设置价格（按人员类型）", notes = "在指定日期范围内批量设置该类型人员的服务成本价和可调度状态。\n\n**关联字典**：\n- staff_type（人员类型）→ staffType路径参数")
     @PutMapping("/type/{staffType}/prices")
     public Result<Void> batchSetPrices(
             @ApiParam("人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER") @PathVariable String staffType,
@@ -45,7 +45,7 @@ public class StaffPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改调度状态（按人员类型）")
+    @ApiOperation(value = "批量修改调度状态（按人员类型）", notes = "批量修改日期范围内的可调度状态，不影响价格。\n\n**关联字典**：\n- staff_type（人员类型）→ staffType路径参数")
     @PutMapping("/type/{staffType}/prices/batch-status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER") @PathVariable String staffType,
@@ -54,7 +54,7 @@ public class StaffPriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("清除价格日历（按人员类型）")
+    @ApiOperation(value = "清除价格日历（按人员类型）", notes = "删除指定日期范围内该类型人员的价格记录。日期格式：yyyy-MM-dd。\n\n**关联字典**：\n- staff_type（人员类型）→ staffType路径参数")
     @DeleteMapping("/type/{staffType}/prices")
     public Result<Void> deletePrices(
             @ApiParam("人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER") @PathVariable String staffType,

`hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java
index beceb5f..ff68d2c 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffTagController.java
@@ -26,7 +26,7 @@ public class StaffTagController {
 
     private final StaffTagService tagService;
 
-    @ApiOperation("预设标签列表（分页）")
+    @ApiOperation(value = "预设标签列表（分页）", notes = "分页查询服务人员标签库，支持按关键词搜索。")
     @GetMapping("/tags")
     public Result<PageResult<StaffTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -35,13 +35,13 @@ public class StaffTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("全部标签列表")
+    @ApiOperation(value = "全部标签列表", notes = "不分页返回所有标签，用于人员编辑时的标签选择。")
     @GetMapping("/tags/all")
     public Result<List<StaffTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建标签")
+    @ApiOperation(value = "创建标签", notes = "创建预设标签，标签名不可重复。")
     @PostMapping("/tag")
     public Result<StaffTagVO> createTag(@ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
                                          HttpServletRequest httpRequest) {
@@ -49,7 +49,7 @@ public class StaffTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "按名称查找或自动创建标签。")
     @PostMapping("/tag/adhoc")
     public Result<StaffTagVO> resolveAdHocTag(@ApiParam("标签名称请求体") @Valid @RequestBody TagCreateRequest request,
                                                HttpServletRequest httpRequest) {
@@ -57,21 +57,21 @@ public class StaffTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("更新标签")
+    @ApiOperation(value = "更新标签", notes = "修改标签名称或颜色。")
     @PutMapping("/tag/{tagId}")
     public Result<StaffTagVO> updateTag(@ApiParam("标签ID") @PathVariable Long tagId,
                                          @ApiParam("标签更新请求") @Valid @RequestBody TagUpdateRequest request) {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并解除所有人员与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("设置人员标签")
+    @ApiOperation(value = "设置人员标签", notes = "全量替换指定人员的标签列表。")
     @PutMapping("/{staffId}/tags")
     public Result<Void> updateStaffTags(@ApiParam("人员ID") @PathVariable Long staffId,
                                          @ApiParam("标签ID列表请求") @Valid @RequestBody StaffTagUpdateRequest request) {
@@ -79,7 +79,7 @@ public class StaffTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量添加/移除标签")
+    @ApiOperation(value = "批量添加/移除标签", notes = "对多个人员批量添加/移除标签。增量操作。")
     @PutMapping("/batch/tags")
     public Result<Void> batchUpdateTags(@ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {
         tagService.batchUpdateTags(request.getStaffIds(), request.getAddTagIds(), request.getRemoveTagIds());

`hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java
index 5467d19..e827b51 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/InternalSuppliesController.java
@@ -17,7 +17,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】备品（Feign调用）")
+@Api(tags = "【内部接口】备品（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/supplies")
 @RequiredArgsConstructor
@@ -25,7 +25,7 @@ public class InternalSuppliesController {
 
     private final SuppliesService suppliesService;
 
-    @ApiOperation("获取备品简要信息")
+    @ApiOperation(value = "获取备品简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个备品的简要信息，返回ID、名称、分类编码、计费类型、状态。不存在时返回错误。\n\n**关联字典**：\n- supplies_category（备品分类，返回字段categoryCode）：CAMPING=露营, CLOTHING=服装, EQUIPMENT=装备, SAFETY=安全\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/item/{suppliesId}")
     public Result<Map<String, Object>> getSuppliesBrief(@PathVariable Long suppliesId) {
         SuppliesItem item = suppliesService.getSuppliesEntity(suppliesId);
@@ -41,7 +41,7 @@ public class InternalSuppliesController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取备品简要信息")
+    @ApiOperation(value = "批量获取备品简要信息", notes = "【仅限内部Feign调用】批量获取备品简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询产品关联的备品资源。\n\n**关联字典**：\n- supplies_category（备品分类，返回字段categoryCode）：CAMPING=露营, CLOTHING=服装, EQUIPMENT=装备, SAFETY=安全\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/items/batch")
     public Result<List<Map<String, Object>>> getSuppliesBatch(@RequestParam @Size(max = 500) List<Long> suppliesIds) {
         List<Map<String, Object>> results = suppliesIds.stream()
@@ -61,9 +61,9 @@ public class InternalSuppliesController {
         return Result.success(results);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配备品并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         suppliesService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java
index 435f28b..964e6fc 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java
@@ -26,7 +26,7 @@ public class SuppliesController {
 
     private final SuppliesService suppliesService;
 
-    @ApiOperation("创建备品")
+    @ApiOperation(value = "创建备品", notes = "新建备品资源（帐篷、睡袋、炊具等物资），初始状态为草稿(status=0)。需走企微审批上架。支持按件(PER_ITEM)和按人(PER_PERSON)计费。\n\n**关联字典**：\n- supplies_category：备品分类（表单选择）\n- billing_type：计费方式（表单选择）")
     @PostMapping("/item")
     public Result<SuppliesVO> createSupplies(
             @ApiParam("备品创建请求") @Valid @RequestBody SuppliesCreateRequest request,
@@ -35,19 +35,19 @@ public class SuppliesController {
         return Result.success(suppliesService.createSupplies(request, adminId));
     }
 
-    @ApiOperation("备品列表")
+    @ApiOperation(value = "备品列表", notes = "分页查询备品列表，支持按名称、状态、分类等条件筛选。\n\n**关联字典**：\n- supplies_category：备品分类（筛选+列表显示）\n- billing_type：计费方式（列表显示）")
     @GetMapping("/items")
     public Result<PageResult<SuppliesListVO>> listSupplies(@ApiParam("备品查询请求") @Valid SuppliesQueryRequest query) {
         return Result.success(suppliesService.listSupplies(query));
     }
 
-    @ApiOperation("备品详情")
+    @ApiOperation(value = "备品详情", notes = "获取备品完整信息，包含素材URL、标签等。\n\n**关联字典**：\n- supplies_category：备品分类（详情显示）\n- billing_type：计费方式（详情显示）")
     @GetMapping("/item/{suppliesId}")
     public Result<SuppliesVO> getSupplies(@ApiParam("备品ID") @PathVariable Long suppliesId) {
         return Result.success(suppliesService.getSupplies(suppliesId));
     }
 
-    @ApiOperation("更新备品")
+    @ApiOperation(value = "更新备品", notes = "更新备品基本信息，不改变当前状态。\n\n**关联字典**：\n- supplies_category：备品分类（表单选择）\n- billing_type：计费方式（表单选择）")
     @PutMapping("/item/{suppliesId}")
     public Result<SuppliesVO> updateSupplies(
             @ApiParam("备品ID") @PathVariable Long suppliesId,
@@ -57,7 +57,7 @@ public class SuppliesController {
         return Result.success(suppliesService.updateSupplies(suppliesId, request, adminId));
     }
 
-    @ApiOperation("删除备品")
+    @ApiOperation(value = "删除备品", notes = "软删除备品。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/item/{suppliesId}")
     public Result<Void> deleteSupplies(
             @ApiParam("备品ID") @PathVariable Long suppliesId,
@@ -68,7 +68,7 @@ public class SuppliesController {
         return Result.success();
     }
 
-    @ApiOperation("提交启用/禁用审批")
+    @ApiOperation(value = "提交启用/禁用审批", notes = "向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。")
     @PostMapping("/item/{suppliesId}/submit-approval")
     public Result<Map<String, String>> submitApproval(
             @ApiParam("备品ID") @PathVariable Long suppliesId,
@@ -80,7 +80,7 @@ public class SuppliesController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("上下架切换")
+    @ApiOperation(value = "上下架切换", notes = "直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/item/{suppliesId}/status")
     public Result<Void> updateStatus(
             @ApiParam("备品ID") @PathVariable Long suppliesId,
@@ -91,7 +91,7 @@ public class SuppliesController {
         return Result.success();
     }
 
-    @ApiOperation("批量上下架")
+    @ApiOperation(value = "批量上下架", notes = "批量修改多个备品的状态，跳过审批流程。")
     @PutMapping("/items/batch/status")
     public Result<Void> batchUpdateStatus(
             @ApiParam("备品状态请求") @Valid @RequestBody SuppliesStatusRequest request,
@@ -103,7 +103,7 @@ public class SuppliesController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个备品。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/items/batch")
     public Result<Void> batchDelete(
             @ApiParam("批量删除请求") @Valid @RequestBody BatchDeleteRequest request,

`hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java
index 7529058..8095ade 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesTagController.java
@@ -27,7 +27,7 @@ public class SuppliesTagController {
 
     private final SuppliesTagService tagService;
 
-    @ApiOperation("获取管理标签列表（分页）")
+    @ApiOperation(value = "获取管理标签列表（分页）", notes = "分页查询备品标签库，支持按关键词搜索。")
     @GetMapping("/tags")
     public Result<PageResult<SuppliesTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -36,13 +36,13 @@ public class SuppliesTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("获取全部标签")
+    @ApiOperation(value = "获取全部标签", notes = "不分页返回所有标签，用于备品编辑时的标签选择下拉。")
     @GetMapping("/tags/all")
     public Result<List<SuppliesTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建管理标签")
+    @ApiOperation(value = "创建管理标签", notes = "创建预设标签，标签名不可重复。")
     @PostMapping("/tag")
     public Result<SuppliesTagVO> createTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -51,7 +51,7 @@ public class SuppliesTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "按名称查找或自动创建标签。")
     @PostMapping("/tag/adhoc")
     public Result<SuppliesTagVO> resolveAdHocTag(
             @ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
@@ -60,7 +60,7 @@ public class SuppliesTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("编辑标签")
+    @ApiOperation(value = "编辑标签", notes = "修改标签名称或颜色，所有关联备品自动生效。")
     @PutMapping("/tag/{tagId}")
     public Result<SuppliesTagVO> updateTag(
             @ApiParam("标签ID") @PathVariable Long tagId,
@@ -68,14 +68,14 @@ public class SuppliesTagController {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并解除所有备品与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("更新备品标签")
+    @ApiOperation(value = "更新备品标签", notes = "全量替换指定备品的标签列表。")
     @PutMapping("/item/{suppliesId}/tags")
     public Result<Void> updateSuppliesTags(
             @ApiParam("备品ID") @PathVariable Long suppliesId,
@@ -87,7 +87,7 @@ public class SuppliesTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量打标签")
+    @ApiOperation(value = "批量打标签", notes = "对多个备品批量添加/移除标签。增量操作。")
     @PutMapping("/items/batch/tags")
     public Result<Void> batchUpdateTags(
             @ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {

`hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java
index 4e672d1..a0dc396 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/InternalVehicleController.java
@@ -17,7 +17,7 @@ import java.util.stream.Collectors;
 
 @Slf4j
 @Validated
-@Api(tags = "【内部接口】车型（Feign调用）")
+@Api(tags = "【内部接口】车型（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/vehicle")
 @RequiredArgsConstructor
@@ -25,7 +25,7 @@ public class InternalVehicleController {
 
     private final VehicleModelService vehicleModelService;
 
-    @ApiOperation("获取车型简要信息")
+    @ApiOperation(value = "获取车型简要信息", notes = "【仅限内部Feign调用】供产品服务获取单个车型的简要信息，返回ID、名称、车辆类型、品牌、座位数、状态。不存在时返回错误。\n\n**关联字典**：\n- vehicle_type（车辆类型，返回字段vehicleType）：CAR=小轿车, SUV=越野车, VAN=商务车, BUS=大巴, MINIBUS=中巴\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/model/{vehicleId}")
     public Result<Map<String, Object>> getVehicleBrief(@PathVariable Long vehicleId) {
         VehicleModel model = vehicleModelService.getVehicleEntity(vehicleId);
@@ -42,7 +42,7 @@ public class InternalVehicleController {
         return Result.success(brief);
     }
 
-    @ApiOperation("批量获取车型简要信息")
+    @ApiOperation(value = "批量获取车型简要信息", notes = "【仅限内部Feign调用】批量获取车型简要信息，最多500个ID。不存在的ID自动过滤。供产品服务批量查询行程关联的车辆资源。\n\n**关联字典**：\n- vehicle_type（车辆类型，返回字段vehicleType）：CAR=小轿车, SUV=越野车, VAN=商务车, BUS=大巴, MINIBUS=中巴\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/models/batch")
     public Result<List<Map<String, Object>>> getVehicleBatch(@RequestParam @Size(max = 500) List<Long> vehicleIds) {
         List<Map<String, Object>> results = vehicleIds.stream()
@@ -63,7 +63,7 @@ public class InternalVehicleController {
         return Result.success(results);
     }
 
-    @ApiOperation("按车辆类型查询车辆")
+    @ApiOperation(value = "按车辆类型查询车辆", notes = "【仅限内部Feign调用】按vehicleType查询第一个匹配的车型。vehicleType如：SEDAN(轿车)、SUV、MPV、BUS(大巴)、MINIBUS(中巴)等。未找到时返回null。\n\n**关联字典**：\n- vehicle_type（车辆类型，请求参数+返回字段vehicleType）：CAR=小轿车, SUV=越野车, VAN=商务车, BUS=大巴, MINIBUS=中巴\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/model/by-type/{vehicleType}")
     public Result<Map<String, Object>> getVehicleByType(@PathVariable String vehicleType) {
         VehicleModel model = vehicleModelService.getVehicleByType(vehicleType);
@@ -80,7 +80,7 @@ public class InternalVehicleController {
         return Result.success(brief);
     }
 
-    @ApiOperation("按名称查询车辆")
+    @ApiOperation(value = "按名称查询车辆", notes = "【仅限内部Feign调用】按车型名称精确查询车辆信息。未找到时返回null。供产品服务通过名称关联车型使用。\n\n**关联字典**：\n- vehicle_type（车辆类型，返回字段vehicleType）：CAR=小轿车, SUV=越野车, VAN=商务车, BUS=大巴, MINIBUS=中巴\n- common_status（状态，返回字段status）：ACTIVE=启用, INACTIVE=停用")
     @GetMapping("/model/by-name/{name}")
     public Result<Map<String, Object>> getVehicleByName(@PathVariable String name) {
         VehicleModel model = vehicleModelService.getVehicleByName(name);
@@ -97,9 +97,9 @@ public class InternalVehicleController {
         return Result.success(brief);
     }
 
-    @ApiOperation("处理审批回调结果")
+    @ApiOperation(value = "处理审批回调结果", notes = "【仅限内部Feign调用】接收企微OA审批回调，按thirdNo匹配车型并更新启用/禁用状态。由hl-callback-service通过MQ消费后调用，幂等处理。\n\n**关联字典**：\n- approval_sp_status（审批状态，请求字段spStatus）")
     @PostMapping("/approval-result")
-    public Result<?> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
+    public Result<Void> handleApprovalResult(@RequestBody ApprovalResultDTO dto) {
         log.info("Received approval result: thirdNo={}, spStatus={}", dto.getThirdNo(), dto.getSpStatus());
         vehicleModelService.handleApprovalResult(dto.getThirdNo(), dto.getSpStatus());
         return Result.success();

`hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java
index de59d9f..37797fd 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java
@@ -25,7 +25,7 @@ public class VehicleModelController {
 
     private final VehicleModelService vehicleModelService;
 
-    @ApiOperation("创建车型")
+    @ApiOperation(value = "创建车型", notes = "新建车型资源（如7座商务车、14座中巴等），初始状态为草稿(status=0)。车型有独立的价格日历用于报价计算。需走企微审批上架。\n\n**关联字典**：\n- vehicle_type：车辆类型（表单选择）")
     @PostMapping("/model")
     public Result<VehicleModelVO> createVehicle(@ApiParam("车型创建请求") @Valid @RequestBody VehicleCreateRequest request,
                                                  HttpServletRequest httpRequest) {
@@ -33,26 +33,26 @@ public class VehicleModelController {
         return Result.success(vehicleModelService.createVehicle(request, adminId));
     }
 
-    @ApiOperation("车型列表")
+    @ApiOperation(value = "车型列表", notes = "分页查询车型列表，支持按名称、状态、车辆类型等条件筛选。\n\n**关联字典**：\n- vehicle_type：车辆类型（筛选+列表显示）")
     @GetMapping("/models")
     public Result<PageResult<VehicleModelListVO>> listVehicles(@ApiParam("车型查询请求") @Valid VehicleQueryRequest query) {
         return Result.success(vehicleModelService.listVehicles(query));
     }
 
-    @ApiOperation("车型全量列表（不分页，用于下拉选择）")
+    @ApiOperation(value = "车型全量列表（不分页，用于下拉选择）", notes = "返回所有车型列表，可选按状态筛选。适用于产品编排时选择车型的下拉选择框。不分页返回全部数据。\n\n**关联字典**：\n- vehicle_type：车辆类型（列表显示）")
     @GetMapping("/models/all")
     public Result<List<VehicleModelListVO>> listAllVehicles(
             @ApiParam("状态筛选：1=上架") @RequestParam(required = false) Integer status) {
         return Result.success(vehicleModelService.listAllVehicles(status));
     }
 
-    @ApiOperation("车型详情")
+    @ApiOperation(value = "车型详情", notes = "获取车型完整信息，包含座位数、品牌、素材URL、标签等。\n\n**关联字典**：\n- vehicle_type：车辆类型（详情显示）")
     @GetMapping("/model/{vehicleId}")
     public Result<VehicleModelVO> getVehicle(@ApiParam("车型ID") @PathVariable Long vehicleId) {
         return Result.success(vehicleModelService.getVehicle(vehicleId));
     }
 
-    @ApiOperation("更新车型")
+    @ApiOperation(value = "更新车型", notes = "更新车型基本信息，不改变当前状态。\n\n**关联字典**：\n- vehicle_type：车辆类型（表单选择）")
     @PutMapping("/model/{vehicleId}")
     public Result<VehicleModelVO> updateVehicle(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                                  @ApiParam("车型更新请求") @Valid @RequestBody VehicleUpdateRequest request,
@@ -61,7 +61,7 @@ public class VehicleModelController {
         return Result.success(vehicleModelService.updateVehicle(vehicleId, request, adminId));
     }
 
-    @ApiOperation("删除车型")
+    @ApiOperation(value = "删除车型", notes = "软删除车型。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/model/{vehicleId}")
     public Result<Void> deleteVehicle(@ApiParam("车型ID") @PathVariable Long vehicleId, HttpServletRequest httpRequest) {
         Long adminId = getAdminId(httpRequest);
@@ -70,7 +70,7 @@ public class VehicleModelController {
         return Result.success();
     }
 
-    @ApiOperation("提交审批")
+    @ApiOperation(value = "提交审批", notes = "向企微OA提交车型启用/禁用审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。")
     @PostMapping("/model/{vehicleId}/submit-approval")
     public Result<Map<String, String>> submitApproval(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                                        @ApiParam("审批提交请求体") @Valid @RequestBody ApprovalSubmitRequest request,
@@ -80,7 +80,7 @@ public class VehicleModelController {
         return Result.success(Map.of("spNo", spNo));
     }
 
-    @ApiOperation("更新状态")
+    @ApiOperation(value = "更新状态", notes = "直接修改车型状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。")
     @PutMapping("/model/{vehicleId}/status")
     public Result<Void> updateStatus(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                       @ApiParam("状态请求体") @Valid @RequestBody VehicleStatusRequest request,
@@ -90,7 +90,7 @@ public class VehicleModelController {
         return Result.success();
     }
 
-    @ApiOperation("批量更新状态")
+    @ApiOperation(value = "批量更新状态", notes = "批量修改多个车型的状态，跳过审批流程。")
     @PutMapping("/models/batch/status")
     public Result<Void> batchUpdateStatus(@ApiParam("批量状态请求体") @Valid @RequestBody VehicleStatusRequest request,
                                            HttpServletRequest httpRequest) {
@@ -98,7 +98,7 @@ public class VehicleModelController {
         return Result.success();
     }
 
-    @ApiOperation("批量删除")
+    @ApiOperation(value = "批量删除", notes = "批量软删除多个车型。仅SUPER_ADMIN或创建者可操作。")
     @DeleteMapping("/models/batch")
     public Result<Void> batchDelete(@ApiParam("批量删除请求体") @Valid @RequestBody VehicleBatchDeleteRequest request,
                                      HttpServletRequest httpRequest) {

`hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java
index 52a68eb..c1bcfba 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarController.java
@@ -27,7 +27,7 @@ public class VehiclePriceCalendarController {
 
     private final VehiclePriceCalendarService priceCalendarService;
 
-    @ApiOperation("查询价格日历")
+    @ApiOperation(value = "查询价格日历", notes = "按月查询车型的每日租赁价格和可调度状态。")
     @GetMapping("/model/{vehicleId}/prices")
     public Result<PriceCalendarVO> getPriceCalendar(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                                      @ApiParam("年份") @RequestParam @Min(2020) @Max(2100) Integer year,
@@ -35,7 +35,7 @@ public class VehiclePriceCalendarController {
         return Result.success(priceCalendarService.getPriceCalendar(vehicleId, year, month));
     }
 
-    @ApiOperation("批量设置价格")
+    @ApiOperation(value = "批量设置价格", notes = "在指定日期范围内批量设置车型的租赁成本价和可调度状态。")
     @PutMapping("/model/{vehicleId}/prices")
     public Result<Void> batchSetPrices(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                         @ApiParam("价格日历设置请求") @Valid @RequestBody PriceCalendarSetRequest request) {
@@ -43,7 +43,7 @@ public class VehiclePriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("批量修改调度状态")
+    @ApiOperation(value = "批量修改调度状态", notes = "批量修改日期范围内车型的可调度状态，不影响价格。")
     @PutMapping("/model/{vehicleId}/prices/batch-status")
     public Result<Void> batchUpdateStatus(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                            @ApiParam("价格日历状态请求") @Valid @RequestBody PriceCalendarStatusRequest request) {
@@ -51,7 +51,7 @@ public class VehiclePriceCalendarController {
         return Result.success();
     }
 
-    @ApiOperation("清除价格日历")
+    @ApiOperation(value = "清除价格日历", notes = "删除指定日期范围内车型的价格记录。日期格式：yyyy-MM-dd。")
     @DeleteMapping("/model/{vehicleId}/prices")
     public Result<Void> deletePrices(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                       @ApiParam("开始日期") @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate startDate,

`hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java` (M)

diff --git a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java
index a7a1b49..b2ad988 100644
--- a/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java
+++ b/hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleTagController.java
@@ -26,7 +26,7 @@ public class VehicleTagController {
 
     private final VehicleTagService tagService;
 
-    @ApiOperation("预设标签列表（分页）")
+    @ApiOperation(value = "预设标签列表（分页）", notes = "分页查询车型标签库，支持按关键词搜索。")
     @GetMapping("/tags")
     public Result<PageResult<VehicleTagVO>> listManagedTags(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -35,13 +35,13 @@ public class VehicleTagController {
         return Result.success(tagService.listManagedTags(page, pageSize, keyword));
     }
 
-    @ApiOperation("全部标签列表")
+    @ApiOperation(value = "全部标签列表", notes = "不分页返回所有标签，用于车型编辑时的标签选择。")
     @GetMapping("/tags/all")
     public Result<List<VehicleTagVO>> listAllTags() {
         return Result.success(tagService.listAllTags());
     }
 
-    @ApiOperation("创建标签")
+    @ApiOperation(value = "创建标签", notes = "创建预设标签，标签名不可重复。")
     @PostMapping("/tag")
     public Result<VehicleTagVO> createTag(@ApiParam("标签创建请求") @Valid @RequestBody TagCreateRequest request,
                                            HttpServletRequest httpRequest) {
@@ -49,7 +49,7 @@ public class VehicleTagController {
         return Result.success(tagService.createTag(request, adminId));
     }
 
-    @ApiOperation("解析自定义标签")
+    @ApiOperation(value = "解析自定义标签", notes = "按名称查找或自动创建标签。")
     @PostMapping("/tag/adhoc")
     public Result<VehicleTagVO> resolveAdHocTag(@ApiParam("标签名称请求体") @Valid @RequestBody TagCreateRequest request,
                                                  HttpServletRequest httpRequest) {
@@ -57,21 +57,21 @@ public class VehicleTagController {
         return Result.success(tagService.resolveAdHocTag(request.getTagName(), adminId));
     }
 
-    @ApiOperation("更新标签")
+    @ApiOperation(value = "更新标签", notes = "修改标签名称或颜色。")
     @PutMapping("/tag/{tagId}")
     public Result<VehicleTagVO> updateTag(@ApiParam("标签ID") @PathVariable Long tagId,
                                            @ApiParam("标签更新请求") @Valid @RequestBody TagUpdateRequest request) {
         return Result.success(tagService.updateTag(tagId, request));
     }
 
-    @ApiOperation("删除标签")
+    @ApiOperation(value = "删除标签", notes = "删除标签并解除所有车型与该标签的关联。")
     @DeleteMapping("/tag/{tagId}")
     public Result<Void> deleteTag(@ApiParam("标签ID") @PathVariable Long tagId) {
         tagService.deleteTag(tagId);
         return Result.success();
     }
 
-    @ApiOperation("设置车型标签")
+    @ApiOperation(value = "设置车型标签", notes = "全量替换指定车型的标签列表。")
     @PutMapping("/model/{vehicleId}/tags")
     public Result<Void> updateVehicleTags(@ApiParam("车型ID") @PathVariable Long vehicleId,
                                            @ApiParam("标签ID列表请求") @Valid @RequestBody VehicleTagUpdateRequest request) {
@@ -79,7 +79,7 @@ public class VehicleTagController {
         return Result.success();
     }
 
-    @ApiOperation("批量添加/移除标签")
+    @ApiOperation(value = "批量添加/移除标签", notes = "对多个车型批量添加/移除标签。增量操作。")
     @PutMapping("/models/batch/tags")
     public Result<Void> batchUpdateTags(@ApiParam("批量标签请求") @Valid @RequestBody BatchTagRequest request) {
         tagService.batchUpdateTags(request.getVehicleIds(), request.getAddTagIds(), request.getRemoveTagIds());

`hl-review-service/src/main/java/com/hulalv/review/config/Knife4jConfig.java` (M)

diff --git a/hl-review-service/src/main/java/com/hulalv/review/config/Knife4jConfig.java b/hl-review-service/src/main/java/com/hulalv/review/config/Knife4jConfig.java
index fde29e7..d3131ce 100644
--- a/hl-review-service/src/main/java/com/hulalv/review/config/Knife4jConfig.java
+++ b/hl-review-service/src/main/java/com/hulalv/review/config/Knife4jConfig.java
@@ -26,18 +26,4 @@ public class Knife4jConfig {
                 .build();
     }
 
-    @Bean
-    public Docket internalReviewApi() {
-        return new Docket(DocumentationType.SWAGGER_2)
-                .groupName("2. 评价内部接口")
-                .apiInfo(new ApiInfoBuilder()
-                        .title("评价内部 API")
-                        .description("评价内部接口（供BFF等服务调用）")
-                        .version("1.0")
-                        .build())
-                .select()
-                .apis(RequestHandlerSelectors.basePackage("com.hulalv.review.controller"))
-                .paths(PathSelectors.ant("/internal/**"))
-                .build();
-    }
 }

`hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java` (M)

diff --git a/hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java b/hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java
index 1781646..ad503eb 100644
--- a/hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java
+++ b/hl-review-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java
@@ -25,19 +25,19 @@ public class AdminReviewController {
 
     private final ReviewService reviewService;
 
-    @ApiOperation("评价列表(支持好中差评/有图/有视频筛选)")
+    @ApiOperation(value = "评价列表(支持好中差评/有图/有视频筛选)", notes = "分页查询全部评价（含待审核/已通过/已拒绝），支持按评价等级、是否有图/视频、目标类型筛选\n\n**关联字典**：\n- review_status：评价审核状态（列表筛选+显示）\n- rating_level：评价等级（列表筛选+显示）")
     @GetMapping("/list")
     public Result<PageResult<ReviewListVO>> listReviews(@ApiParam("评价查询条件") ReviewQueryRequest request) {
         return Result.success(reviewService.listReviews(request));
     }
 
-    @ApiOperation("评价详情")
+    @ApiOperation(value = "评价详情", notes = "**关联字典**：\n- review_status：评价审核状态（显示）\n- rating_level：评价等级（显示）")
     @GetMapping("/{reviewId}")
     public Result<ReviewVO> getReviewDetail(@ApiParam("评价ID") @PathVariable Long reviewId) {
         return Result.success(reviewService.getReviewDetail(reviewId));
     }
 
-    @ApiOperation("通过评价")
+    @ApiOperation(value = "通过评价", notes = "审核通过评价，通过后评价在小程序端公开展示。状态流转：PENDING_REVIEW → APPROVED")
     @PostMapping("/{reviewId}/approve")
     public Result<Void> approve(@ApiParam("评价ID") @PathVariable Long reviewId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -47,7 +47,7 @@ public class AdminReviewController {
         return Result.success();
     }
 
-    @ApiOperation("拒绝评价")
+    @ApiOperation(value = "拒绝评价", notes = "审核拒绝评价，需填写拒绝原因。拒绝后评价不公开展示。状态流转：PENDING_REVIEW → REJECTED")
     @PostMapping("/{reviewId}/reject")
     public Result<Void> reject(@ApiParam("评价ID") @PathVariable Long reviewId,
                                @ApiParam("拒绝请求") @Valid @RequestBody RejectRequest body,
@@ -59,7 +59,7 @@ public class AdminReviewController {
         return Result.success();
     }
 
-    @ApiOperation("覆盖通过(机器拒绝的)")
+    @ApiOperation(value = "覆盖通过(机器拒绝的)", notes = "对阿里云内容审核自动拒绝的评价进行人工覆盖通过。状态流转：AUTO_REJECTED → APPROVED")
     @PostMapping("/{reviewId}/override-approve")
     public Result<Void> overrideApprove(@ApiParam("评价ID") @PathVariable Long reviewId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -69,7 +69,8 @@ public class AdminReviewController {
         return Result.success();
     }
 
-    @ApiOperation("回复评价(每条评价仅可回复一次)")
+    @ApiOperation(value = "回复评价(每条评价仅可回复一次)",
+            notes = "管理员回复用户评价，回复内容在小程序端公开展示。每条评价仅允许回复一次，不可修改。\n\n**权限**：需管理员登录。")
     @PostMapping("/{reviewId}/reply")
     public Result<Void> adminReply(@ApiParam("评价ID") @PathVariable Long reviewId,
                                     @ApiParam("回复内容") @Valid @RequestBody AdminReplyRequest body,

`hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java` (M)

diff --git a/hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java b/hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java
index b3dd6a3..62fb7d0 100644
--- a/hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java
+++ b/hl-review-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java
@@ -19,7 +19,7 @@ import javax.validation.Valid;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "【内部接口】小程序评价（Feign调用）")
+@Api(tags = "【内部接口】小程序评价（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/review")
 @RequiredArgsConstructor
@@ -27,7 +27,7 @@ public class InternalMpReviewController {
 
     private final ReviewService reviewService;
 
-    @ApiOperation("创建评价(仅针对产品，每个订单仅可评价一次)")
+    @ApiOperation(value = "创建评价(仅针对产品，每个订单仅可评价一次)", notes = "**关联字典**：\n- review_status：评价审核状态（返回字段）\n- rating_level：评价等级（返回字段）")
     @PostMapping("/create")
     public Result<ReviewVO> createReview(@Valid @RequestBody CreateReviewRequest body,
                                          HttpServletRequest request) {
@@ -35,13 +35,14 @@ public class InternalMpReviewController {
         return Result.success(reviewService.createReview(userId, body));
     }
 
-    @ApiOperation("检查订单是否已评价")
+    @ApiOperation(value = "检查订单是否已评价",
+            notes = "内部服务间调用。检查指定订单是否已有评价记录，用于小程序端订单详情页控制评价入口的显示。")
     @GetMapping("/order/{orderId}/reviewed")
     public Result<Boolean> isOrderReviewed(@PathVariable Long orderId) {
         return Result.success(reviewService.isOrderReviewed(orderId));
     }
 
-    @ApiOperation("我的评价列表")
+    @ApiOperation(value = "我的评价列表", notes = "**关联字典**：\n- review_status：评价审核状态（显示）\n- rating_level：评价等级（显示）")
     @GetMapping("/my")
     public Result<PageResult<MpReviewVO>> getMyReviews(MpReviewQueryRequest query,
                                                         HttpServletRequest request) {
@@ -49,13 +50,13 @@ public class InternalMpReviewController {
         return Result.success(reviewService.getMyReviews(userId, query));
     }
 
-    @ApiOperation("某目标的已通过评价(公开，支持好中差评/有图/有视频筛选)")
+    @ApiOperation(value = "某目标的已通过评价(公开，支持好中差评/有图/有视频筛选)", notes = "**关联字典**：\n- rating_level：评价等级（筛选+显示）")
     @GetMapping("/target")
     public Result<PageResult<MpReviewVO>> getTargetReviews(@Valid TargetReviewQueryRequest query) {
         return Result.success(reviewService.getTargetReviews(query));
     }
 
-    @ApiOperation("关键词搜索评价(公开)")
+    @ApiOperation(value = "关键词搜索评价(公开)", notes = "**关联字典**：\n- rating_level：评价等级（显示）")
     @GetMapping("/search")
     public Result<PageResult<MpReviewVO>> searchReviews(
             @ApiParam("搜索关键词") @RequestParam String keyword,
@@ -66,14 +67,15 @@ public class InternalMpReviewController {
         return Result.success(reviewService.searchReviews(keyword, targetType, targetId, page, pageSize));
     }
 
-    @ApiOperation("首页精选评价")
+    @ApiOperation(value = "首页精选评价", notes = "**关联字典**：\n- rating_level：评价等级（显示）")
     @GetMapping("/featured")
     public Result<List<MpReviewVO>> getFeaturedReviews(
             @ApiParam("数量限制") @RequestParam(defaultValue = "5") Integer limit) {
         return Result.success(reviewService.getFeaturedReviews(limit));
     }
 
-    @ApiOperation("订单可评价目标列表")
+    @ApiOperation(value = "订单可评价目标列表",
+            notes = "内部服务间调用。返回订单关联的可评价目标（产品、定制师等），用于评价页面选择评价对象。已评价的目标不会重复出现。")
     @GetMapping("/order/{orderId}/reviewable-targets")
     public Result<List<Map<String, Object>>> getReviewableTargets(
             @PathVariable Long orderId, HttpServletRequest request) {
@@ -81,7 +83,8 @@ public class InternalMpReviewController {
         return Result.success(reviewService.getReviewableTargets(orderId, userId));
     }
 
-    @ApiOperation("点赞/取消点赞评价")
+    @ApiOperation(value = "点赞/取消点赞评价",
+            notes = "内部服务间调用。切换当前用户对评价的点赞状态（toggle），返回最新点赞状态和点赞总数。")
     @PostMapping("/{reviewId}/like")
     public Result<Map<String, Object>> toggleLike(@PathVariable Long reviewId,
                                                     HttpServletRequest request) {
@@ -89,7 +92,8 @@ public class InternalMpReviewController {
         return Result.success(reviewService.toggleLike(reviewId, userId));
     }
 
-    @ApiOperation("检查是否已点赞")
+    @ApiOperation(value = "检查是否已点赞",
+            notes = "内部服务间调用。检查当前用户是否已对指定评价点赞，用于小程序端渲染点赞按钮状态。")
     @GetMapping("/{reviewId}/like/check")
     public Result<Boolean> checkLiked(@PathVariable Long reviewId,
                                        HttpServletRequest request) {
@@ -97,7 +101,8 @@ public class InternalMpReviewController {
         return Result.success(reviewService.checkLiked(reviewId, userId));
     }
 
-    @ApiOperation("同步评价点赞数（供通用点赞服务回调）")
+    @ApiOperation(value = "同步评价点赞数（供通用点赞服务回调）",
+            notes = "内部服务间调用。通用点赞服务（user-service）发生点赞变化后回调此接口，同步更新评价表的点赞计数字段。")
     @PostMapping("/{reviewId}/sync-like-count")
     public Result<Void> syncLikeCount(@PathVariable Long reviewId,
                                        @RequestParam int likeCount) {

`hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java` (M)

diff --git a/hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java b/hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java
index 0567412..7e5f1cb 100644
--- a/hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java
+++ b/hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java
@@ -21,7 +21,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
-@Api(tags = "【内部接口】评价统计（Feign调用）")
+@Api(tags = "【内部接口】评价统计（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/review")
 @RequiredArgsConstructor
@@ -29,14 +29,14 @@ public class InternalReviewController {
 
     private final ReviewService reviewService;
 
-    @ApiOperation("目标评价统计(平均分,数量)")
+    @ApiOperation(value = "目标评价统计(平均分,数量)", notes = "**关联字典**：\n- rating_level：评价等级（统计维度）")
     @GetMapping("/target-stats")
     public Result<ReviewStatsVO> getTargetStats(@RequestParam String targetType,
                                                  @RequestParam Long targetId) {
         return Result.success(reviewService.getTargetStats(targetType, targetId));
     }
 
-    @ApiOperation("目标已通过评价列表")
+    @ApiOperation(value = "目标已通过评价列表", notes = "**关联字典**：\n- rating_level：评价等级（显示）")
     @GetMapping("/target-list")
     public Result<PageResult<MpReviewVO>> getTargetReviews(
             @RequestParam String targetType,
@@ -46,7 +46,7 @@ public class InternalReviewController {
         return Result.success(reviewService.getTargetReviewsInternal(targetType, targetId, page, pageSize));
     }
 
-    @ApiOperation("批量目标评价统计(聚合多个targetId)")
+    @ApiOperation(value = "批量目标评价统计(聚合多个targetId)", notes = "**关联字典**：\n- rating_level：评价等级（统计维度）")
     @GetMapping("/stats-by-targets")
     public Result<ReviewStatsVO> getStatsByTargetIds(
             @RequestParam String targetType,
@@ -55,7 +55,7 @@ public class InternalReviewController {
         return Result.success(reviewService.getStatsByTargetIds(targetType, ids));
     }
 
-    @ApiOperation("批量目标已通过评价列表(聚合多个targetId)")
+    @ApiOperation(value = "批量目标已通过评价列表(聚合多个targetId)", notes = "**关联字典**：\n- rating_level：评价等级（显示）")
     @GetMapping("/reviews-by-targets")
     public Result<PageResult<MpReviewVO>> getReviewsByTargetIds(
             @RequestParam String targetType,
@@ -66,13 +66,13 @@ public class InternalReviewController {
         return Result.success(reviewService.getReviewsByTargetIds(targetType, ids, page, pageSize));
     }
 
-    @ApiOperation("产品精选评价(最高评分+最高点赞+统计)")
+    @ApiOperation(value = "产品精选评价(最高评分+最高点赞+统计)", notes = "**关联字典**：\n- rating_level：评价等级（显示）")
     @GetMapping("/product-highlights")
     public Result<Map<String, Object>> getProductHighlights(@RequestParam Long productId) {
         return Result.success(reviewService.getProductHighlightReviews(productId));
     }
 
-    @ApiOperation("定制师已通过评价列表")
+    @ApiOperation(value = "定制师已通过评价列表", notes = "**关联字典**：\n- rating_level：评价等级（筛选+显示）")
     @GetMapping("/customizer-reviews")
     public Result<PageResult<MpReviewVO>> getCustomizerReviews(
             @RequestParam Long customizerId,
@@ -82,7 +82,8 @@ public class InternalReviewController {
         return Result.success(reviewService.getCustomizerReviews(customizerId, page, pageSize, ratingLevel));
     }
 
-    @ApiOperation("定制师评价统计(总数/平均分/好评率)")
+    @ApiOperation(value = "定制师评价统计(总数/平均分/好评率)",
+            notes = "内部服务间调用。返回指定定制师的评价汇总统计：总评价数、平均评分、好评率等。用于定制师主页展示服务评价。")
     @GetMapping("/customizer-review-stats")
     public Result<java.util.Map<String, Object>> getCustomizerReviewStats(
             @RequestParam Long customizerId) {

`hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java` (M)

diff --git a/hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java b/hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java
index 75b6a7a..0629ed1 100644
--- a/hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java
+++ b/hl-task-service/src/main/java/com/hulalv/task/controller/BoardController.java
@@ -33,7 +33,7 @@ public class BoardController {
 
     // ======================= Board CRUD =======================
 
-    @ApiOperation("获取可见看板列表")
+    @ApiOperation(value = "获取可见看板列表", notes = "返回当前管理员可见的看板列表：超级管理员可见所有看板，普通管理员仅可见自己创建的或作为成员的看板")
     @GetMapping("/boards")
     public Result<List<BoardVO>> getBoards(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -41,7 +41,7 @@ public class BoardController {
         return Result.success(boardService.getVisibleBoards(adminId, role));
     }
 
-    @ApiOperation("看板详情")
+    @ApiOperation(value = "看板详情", notes = "返回看板基本信息（名称、描述、创建者），不含任务数据。查看任务请使用「获取看板任务」接口")
     @GetMapping("/board/{boardId}")
     public Result<BoardVO> getBoardDetail(@ApiParam("看板ID") @PathVariable Long boardId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -49,7 +49,8 @@ public class BoardController {
         return Result.success(boardService.getBoardDetail(boardId, adminId, role));
     }
 
-    @ApiOperation("创建自定义看板")
+    @ApiOperation(value = "创建自定义看板",
+            notes = "创建自定义看板，自动添加创建者为看板成员，并创建默认状态列（待办、进行中、已完成）。\n\n**权限**：需管理员登录。")
     @OperationLog(value = "创建看板", module = "任务看板")
     @PostMapping("/board")
     public Result<BoardVO> createBoard(@ApiParam("创建看板请求") @Valid @RequestBody CreateBoardRequest req, HttpServletRequest request) {
@@ -57,7 +58,8 @@ public class BoardController {
         return Result.success(boardService.createBoard(req, adminId));
     }
 
-    @ApiOperation("更新看板")
+    @ApiOperation(value = "更新看板",
+            notes = "更新看板的名称和描述。仅看板创建者或超级管理员可操作。\n\n**权限**：需管理员登录，且为看板创建者或超级管理员。")
     @OperationLog(value = "编辑看板", module = "任务看板")
     @PutMapping("/board/{boardId}")
     public Result<BoardVO> updateBoard(@ApiParam("看板ID") @PathVariable Long boardId,
@@ -68,7 +70,7 @@ public class BoardController {
         return Result.success(boardService.updateBoard(boardId, req, adminId, role));
     }
 
-    @ApiOperation("删除看板")
+    @ApiOperation(value = "删除看板", notes = "删除看板及其下所有状态列和任务（级联删除）。仅看板创建者或超级管理员可操作")
     @OperationLog(value = "删除看板", module = "任务看板")
     @DeleteMapping("/board/{boardId}")
     public Result<Void> deleteBoard(@ApiParam("看板ID") @PathVariable Long boardId, HttpServletRequest request) {
@@ -80,13 +82,14 @@ public class BoardController {
 
     // ======================= Status columns =======================
 
-    @ApiOperation("获取看板状态列")
+    @ApiOperation(value = "获取看板状态列", notes = "返回看板的所有状态列（如待办、进行中、已完成），按排序字段升序排列。拖拽任务到不同状态列实现状态流转")
     @GetMapping("/board/{boardId}/statuses")
     public Result<List<BoardStatusVO>> getStatuses(@ApiParam("看板ID") @PathVariable Long boardId) {
         return Result.success(boardStatusService.getStatuses(boardId));
     }
 
-    @ApiOperation("创建状态列")
+    @ApiOperation(value = "创建状态列",
+            notes = "在看板中创建新的状态列（如测试中、待发布等），自动排到末尾。任务通过拖拽在不同状态列间流转。\n\n**权限**：需管理员登录且为看板成员。")
     @OperationLog(value = "新增状态列", module = "任务看板")
     @PostMapping("/board/{boardId}/status")
     public Result<BoardStatusVO> createStatus(@ApiParam("看板ID") @PathVariable Long boardId,
@@ -97,7 +100,8 @@ public class BoardController {
         return Result.success(boardStatusService.createStatus(boardId, req, adminId, role));
     }
 
-    @ApiOperation("更新状态列")
+    @ApiOperation(value = "更新状态列",
+            notes = "更新状态列的名称和颜色。\n\n**权限**：需管理员登录且为看板成员。")
     @OperationLog(value = "编辑状态列", module = "任务看板")
     @PutMapping("/status/{statusId}")
     public Result<BoardStatusVO> updateStatus(@ApiParam("状态列ID") @PathVariable Long statusId,
@@ -108,7 +112,7 @@ public class BoardController {
         return Result.success(boardStatusService.updateStatus(statusId, req, adminId, role));
     }
 
-    @ApiOperation("删除状态列")
+    @ApiOperation(value = "删除状态列", notes = "删除看板的状态列。如果状态列下有任务则不允许删除，需先移动或删除任务")
     @OperationLog(value = "删除状态列", module = "任务看板")
     @DeleteMapping("/status/{statusId}")
     public Result<Void> deleteStatus(@ApiParam("状态列ID") @PathVariable Long statusId,
@@ -119,7 +123,7 @@ public class BoardController {
         return Result.success();
     }
 
-    @ApiOperation("状态列排序")
+    @ApiOperation(value = "状态列排序", notes = "批量更新状态列的排序顺序。传入状态列ID数组，数组下标即为新的排序值。操作完成后通过WebSocket推送STATUS_REORDERED事件")
     @PutMapping("/board/{boardId}/status/sort")
     public Result<Void> sortStatuses(@ApiParam("看板ID") @PathVariable Long boardId,
                                      @ApiParam("状态列排序请求") @Valid @RequestBody StatusSortRequest req,
@@ -133,13 +137,14 @@ public class BoardController {
 
     // ======================= Board Members =======================
 
-    @ApiOperation("获取看板成员")
+    @ApiOperation(value = "获取看板成员", notes = "返回看板的所有成员列表，包含成员的管理员ID和姓名")
     @GetMapping("/board/{boardId}/members")
     public Result<List<BoardMemberVO>> getMembers(@ApiParam("看板ID") @PathVariable Long boardId) {
         return Result.success(boardMemberService.getMembers(boardId));
     }
 
-    @ApiOperation("添加成员")
+    @ApiOperation(value = "添加成员",
+            notes = "批量添加管理员为看板成员，成为成员后可以查看看板、创建和操作任务。\n\n**权限**：需管理员登录，且为看板创建者或超级管理员。")
     @OperationLog(value = "添加看板成员", module = "任务看板")
     @PostMapping("/board/{boardId}/members")
     public Result<Void> addMembers(@ApiParam("看板ID") @PathVariable Long boardId,
@@ -151,7 +156,7 @@ public class BoardController {
         return Result.success();
     }
 
-    @ApiOperation("移除成员")
+    @ApiOperation(value = "移除成员", notes = "从看板中移除指定成员。仅看板创建者或超级管理员可操作，不能移除创建者自己")
     @OperationLog(value = "移除看板成员", module = "任务看板")
     @DeleteMapping("/board/{boardId}/member/{targetAdminId}")
     public Result<Void> removeMember(@ApiParam("看板ID") @PathVariable Long boardId,

`hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java` (M)

diff --git a/hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java b/hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java
index 8593e4d..c85aeca 100644
--- a/hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java
+++ b/hl-task-service/src/main/java/com/hulalv/task/controller/TaskController.java
@@ -31,7 +31,7 @@ public class TaskController {
 
     // ======================= Tasks =======================
 
-    @ApiOperation("获取看板任务(按状态分组)")
+    @ApiOperation(value = "获取看板任务(按状态分组)", notes = "返回看板下所有任务，按状态列分组。支持按优先级(HIGH/MEDIUM/LOW)和负责人筛选，每组内按排序值升序排列\n\n**关联字典**：\n- task_priority：任务优先级（列表筛选+显示）")
     @GetMapping("/board/{boardId}/tasks")
     public Result<List<BoardTasksVO>> getBoardTasks(@ApiParam("看板ID") @PathVariable Long boardId,
                                                      @ApiParam("优先级") @RequestParam(required = false) String priority,
@@ -42,7 +42,7 @@ public class TaskController {
         return Result.success(taskService.getBoardTasks(boardId, adminId, role, priority, assigneeId));
     }
 
-    @ApiOperation("任务详情")
+    @ApiOperation(value = "任务详情", notes = "返回任务完整信息，包含子任务列表、负责人信息、附件列表等\n\n**关联字典**：\n- task_priority：任务优先级（显示）")
     @GetMapping("/{taskId}")
     public Result<TaskVO> getTaskDetail(@ApiParam("任务ID") @PathVariable Long taskId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -50,7 +50,7 @@ public class TaskController {
         return Result.success(taskService.getTaskDetail(taskId, adminId, role));
     }
 
-    @ApiOperation("创建任务")
+    @ApiOperation(value = "创建任务", notes = "在指定看板和状态列下创建任务。创建成功后通过WebSocket推送TASK_CREATED事件，并通知被分配的负责人\n\n**关联字典**：\n- task_priority：任务优先级（创建时选择）")
     @OperationLog(value = "创建任务", module = "任务看板")
     @PostMapping
     public Result<TaskVO> createTask(@ApiParam("创建任务请求") @Valid @RequestBody CreateTaskRequest req, HttpServletRequest request) {
@@ -62,7 +62,8 @@ public class TaskController {
         return Result.success(vo);
     }
 
-    @ApiOperation("更新任务")
+    @ApiOperation(value = "更新任务",
+            notes = "更新任务的标题、描述、优先级、截止日期、负责人等信息。更新后通过WebSocket推送TASK_UPDATED事件，如果修改了负责人则额外通知新负责人。\n\n**权限**：需管理员登录且为看板成员。\n\n**关联字典**：\n- task_priority：任务优先级（编辑时选择）")
     @OperationLog(value = "编辑任务", module = "任务看板")
     @PutMapping("/{taskId}")
     public Result<TaskVO> updateTask(@ApiParam("任务ID") @PathVariable Long taskId,
@@ -78,7 +79,7 @@ public class TaskController {
         return Result.success(vo);
     }
 
-    @ApiOperation("变更任务状态")
+    @ApiOperation(value = "变更任务状态", notes = "将任务移动到指定状态列（拖拽操作），自动记录状态变更到时间线，并通过WebSocket推送TASK_STATUS_CHANGED事件")
     @PutMapping("/{taskId}/status")
     public Result<Void> changeStatus(@ApiParam("任务ID") @PathVariable Long taskId,
                                      @ApiParam("变更状态请求") @Valid @RequestBody ChangeStatusRequest req,
@@ -91,7 +92,7 @@ public class TaskController {
         return Result.success();
     }
 
-    @ApiOperation("任务排序")
+    @ApiOperation(value = "任务排序", notes = "更新任务在同一状态列内的排序位置，用于拖拽排序")
     @PutMapping("/{taskId}/sort")
     public Result<Void> sortTasks(@ApiParam("任务ID") @PathVariable Long taskId,
                                   @ApiParam("任务排序请求") @Valid @RequestBody TaskSortRequest req,
@@ -102,7 +103,8 @@ public class TaskController {
         return Result.success();
     }
 
-    @ApiOperation("删除任务")
+    @ApiOperation(value = "删除任务",
+            notes = "删除任务及其所有子任务、评论和时间线记录（级联删除）。删除后通过WebSocket推送TASK_DELETED事件。\n\n**权限**：需管理员登录且为看板成员。")
     @OperationLog(value = "删除任务", module = "任务看板")
     @DeleteMapping("/{taskId}")
     public Result<Void> deleteTask(@ApiParam("任务ID") @PathVariable Long taskId, HttpServletRequest request) {
@@ -117,7 +119,8 @@ public class TaskController {
 
     // ======================= Subtasks =======================
 
-    @ApiOperation("创建子任务")
+    @ApiOperation(value = "创建子任务",
+            notes = "在指定任务下创建子任务（待办项），用于拆分任务的执行步骤。子任务默认为未完成状态。\n\n**权限**：需管理员登录且为看板成员。")
     @PostMapping("/{taskId}/subtask")
     public Result<SubtaskVO> createSubtask(@ApiParam("任务ID") @PathVariable Long taskId,
                                             @ApiParam("创建子任务请求") @Valid @RequestBody CreateSubtaskRequest req,
@@ -128,7 +131,7 @@ public class TaskController {
         return Result.success(vo);
     }
 
-    @ApiOperation("切换子任务完成状态")
+    @ApiOperation(value = "切换子任务完成状态", notes = "切换子任务的完成/未完成状态（toggle），完成状态切换会自动记录到任务时间线")
     @PutMapping("/subtask/{subtaskId}/toggle")
     public Result<Void> toggleSubtask(@ApiParam("子任务ID") @PathVariable Long subtaskId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -137,7 +140,8 @@ public class TaskController {
         return Result.success();
     }
 
-    @ApiOperation("删除子任务")
+    @ApiOperation(value = "删除子任务",
+            notes = "删除指定子任务。\n\n**权限**：需管理员登录且为看板成员。")
     @DeleteMapping("/subtask/{subtaskId}")
     public Result<Void> deleteSubtask(@ApiParam("子任务ID") @PathVariable Long subtaskId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -148,7 +152,7 @@ public class TaskController {
 
     // ======================= Timeline (comments + activities) =======================
 
-    @ApiOperation("获取任务时间线")
+    @ApiOperation(value = "获取任务时间线", notes = "返回任务的完整操作记录，包含评论和系统自动记录的状态变更、人员分配等活动，按时间正序排列")
     @GetMapping("/{taskId}/timeline")
     public Result<List<TimelineItemVO>> getTimeline(@ApiParam("任务ID") @PathVariable Long taskId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -156,7 +160,7 @@ public class TaskController {
         return Result.success(commentService.getTimeline(taskId, adminId, role));
     }
 
-    @ApiOperation("添加评论")
+    @ApiOperation(value = "添加评论", notes = "在任务时间线中添加评论，添加后自动通知任务负责人")
     @PostMapping("/{taskId}/comment")
     public Result<TimelineItemVO> addComment(@ApiParam("任务ID") @PathVariable Long taskId,
                                               @ApiParam("创建评论请求") @Valid @RequestBody CreateCommentRequest req,
@@ -168,7 +172,7 @@ public class TaskController {
         return Result.success(item);
     }
 
-    @ApiOperation("删除评论")
+    @ApiOperation(value = "删除评论", notes = "仅评论作者本人可删除自己的评论，系统自动生成的活动记录不可删除")
     @DeleteMapping("/comment/{commentId}")
     public Result<Void> deleteComment(@ApiParam("评论ID") @PathVariable Long commentId, HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");

`hl-user-service/src/main/java/com/hulalv/user/config/Knife4jConfig.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/config/Knife4jConfig.java b/hl-user-service/src/main/java/com/hulalv/user/config/Knife4jConfig.java
index cf77842..eafa329 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/config/Knife4jConfig.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/config/Knife4jConfig.java
@@ -28,8 +28,7 @@ public class Knife4jConfig {
                 .select()
                 .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
                 .paths(PathSelectors.ant("/user/**")
-                        .or(PathSelectors.ant("/dict/**"))
-                        .or(PathSelectors.ant("/internal/mp/**")))
+                        .or(PathSelectors.ant("/dict/**")))
                 .build();
     }
 
@@ -168,15 +167,6 @@ public class Knife4jConfig {
                 .build();
     }
 
-    @Bean
-    public Docket internalApi() {
-        return baseDocket("3. 内部接口(Feign)")
-                .select()
-                .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
-                .paths(PathSelectors.ant("/internal/**"))
-                .build();
-    }
-
     private Predicate<String> pathsFor(String... basePaths) {
         Predicate<String> combined = s -> false;
         for (String path : basePaths) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java
index 10fe201..c012fce 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminAgreementController.java
@@ -22,7 +22,9 @@ public class AdminAgreementController {
 
     private final AgreementService agreementService;
 
-    @ApiOperation("协议列表")
+    @ApiOperation(value = "协议列表", notes = "分页查询用户协议列表，支持按关键词和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）")
     @GetMapping
     public Result<PageResult<AgreementVO>> listAgreements(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -32,20 +34,30 @@ public class AdminAgreementController {
         return Result.success(agreementService.listAgreements(page, pageSize, keyword, status));
     }
 
-    @ApiOperation("协议详情")
+    @ApiOperation(value = "协议详情",
+            notes = "获取指定用户协议的详细信息，包括标题、内容（富文本）、版本号等。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- common_status（通用状态）：返回字段status（0=禁用, 1=启用）")
     @GetMapping("/{id}")
     public Result<AgreementVO> getAgreement(@ApiParam("协议ID") @PathVariable Long id) {
         return Result.success(agreementService.getAgreement(id));
     }
 
-    @ApiOperation("新增协议")
+    @ApiOperation(value = "新增协议",
+            notes = "创建新的用户协议，如用户服务协议、隐私政策等。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：协议类型（type）需唯一，同一类型不能重复创建。内容支持富文本。")
     @OperationLog(value = "新增协议", module = "用户协议管理")
     @PostMapping
     public Result<AgreementVO> createAgreement(@Valid @RequestBody AgreementRequest request) {
         return Result.success(agreementService.createAgreement(request));
     }
 
-    @ApiOperation("编辑协议")
+    @ApiOperation(value = "编辑协议",
+            notes = "更新指定用户协议的标题、内容、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：修改后小程序端会实时展示新内容。")
     @OperationLog(value = "编辑协议", module = "用户协议管理")
     @PutMapping("/{id}")
     public Result<AgreementVO> updateAgreement(@ApiParam("协议ID") @PathVariable Long id,
@@ -53,7 +65,10 @@ public class AdminAgreementController {
         return Result.success(agreementService.updateAgreement(id, request));
     }
 
-    @ApiOperation("删除协议")
+    @ApiOperation(value = "删除协议",
+            notes = "删除指定的用户协议记录（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序端将无法查看该协议。")
     @OperationLog(value = "删除协议", module = "用户协议管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteAgreement(@ApiParam("协议ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java
index 5c47fa0..eec06ab 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminBannerController.java
@@ -23,7 +23,9 @@ public class AdminBannerController {
 
     private final BannerService bannerService;
 
-    @ApiOperation("Banner列表")
+    @ApiOperation(value = "Banner列表", notes = "分页查询Banner列表，支持按关键词和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）")
     @GetMapping
     public Result<PageResult<BannerVO>> listBanners(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -34,13 +36,20 @@ public class AdminBannerController {
         return Result.success(result);
     }
 
-    @ApiOperation("Banner详情")
+    @ApiOperation(value = "Banner详情",
+            notes = "获取指定Banner的详细信息，包括标题、图片、跳转链接、排序等。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- common_status（通用状态）：返回字段status（0=禁用, 1=启用）")
     @GetMapping("/{id}")
     public Result<BannerVO> getBanner(@ApiParam("轮播图ID") @PathVariable Long id) {
         return Result.success(bannerService.getBanner(id));
     }
 
-    @ApiOperation("创建Banner")
+    @ApiOperation(value = "创建Banner",
+            notes = "创建新的首页轮播图，包括标题、封面图、跳转链接、排序等。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：创建后默认为启用状态，小程序端将按排序展示。")
     @OperationLog(value = "创建Banner", module = "Banner管理")
     @PostMapping
     public Result<BannerVO> createBanner(@ApiParam("轮播图创建请求") @Valid @RequestBody BannerRequest request,
@@ -49,7 +58,9 @@ public class AdminBannerController {
         return Result.success(bannerService.createBanner(request, adminId));
     }
 
-    @ApiOperation("更新Banner")
+    @ApiOperation(value = "更新Banner",
+            notes = "更新指定Banner的标题、封面图、跳转链接、排序、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "更新Banner", module = "Banner管理")
     @PutMapping("/{id}")
     public Result<BannerVO> updateBanner(@ApiParam("轮播图ID") @PathVariable Long id,
@@ -57,7 +68,10 @@ public class AdminBannerController {
         return Result.success(bannerService.updateBanner(id, request));
     }
 
-    @ApiOperation("删除Banner")
+    @ApiOperation(value = "删除Banner",
+            notes = "删除指定的Banner记录（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序首页将不再展示该Banner。")
     @OperationLog(value = "删除Banner", module = "Banner管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteBanner(@ApiParam("轮播图ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java
index 6080439..786b6ad 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminContactController.java
@@ -22,7 +22,10 @@ public class AdminContactController {
 
     private final ContactService contactService;
 
-    @ApiOperation("联系方式列表")
+    @ApiOperation(value = "联系方式列表", notes = "分页查询联系方式列表，支持按关键词和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- contact_channel_type（联系渠道类型）：返回字段channelType（PHONE=电话, WECHAT=微信, EMAIL=邮箱等）\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status")
     @GetMapping
     public Result<PageResult<ContactVO>> listContacts(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -33,20 +36,27 @@ public class AdminContactController {
         return Result.success(result);
     }
 
-    @ApiOperation("联系方式详情")
+    @ApiOperation(value = "联系方式详情", notes = "获取指定联系方式的详细信息。"
+            + "\n\n**关联字典**：\n"
+            + "- contact_channel_type（联系渠道类型）：返回字段channelType\n"
+            + "- common_status（通用状态）：返回字段status")
     @GetMapping("/{id}")
     public Result<ContactVO> getContact(@ApiParam("联系方式ID") @PathVariable Long id) {
         return Result.success(contactService.getContact(id));
     }
 
-    @ApiOperation("创建联系方式")
+    @ApiOperation(value = "创建联系方式", notes = "新增一条联系方式记录。"
+            + "\n\n**关联字典**：\n"
+            + "- contact_channel_type（联系渠道类型）：请求字段channelType")
     @OperationLog(value = "创建联系方式", module = "联系我们管理")
     @PostMapping
     public Result<ContactVO> createContact(@ApiParam("联系方式创建请求") @Valid @RequestBody ContactRequest request) {
         return Result.success(contactService.createContact(request));
     }
 
-    @ApiOperation("更新联系方式")
+    @ApiOperation(value = "更新联系方式", notes = "更新指定联系方式记录。"
+            + "\n\n**关联字典**：\n"
+            + "- contact_channel_type（联系渠道类型）：请求字段channelType")
     @OperationLog(value = "更新联系方式", module = "联系我们管理")
     @PutMapping("/{id}")
     public Result<ContactVO> updateContact(@ApiParam("联系方式ID") @PathVariable Long id,
@@ -54,7 +64,10 @@ public class AdminContactController {
         return Result.success(contactService.updateContact(id, request));
     }
 
-    @ApiOperation("删除联系方式")
+    @ApiOperation(value = "删除联系方式",
+            notes = "删除指定的联系方式记录（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序端将不再展示该联系方式。")
     @OperationLog(value = "删除联系方式", module = "联系我们管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteContact(@ApiParam("联系方式ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java
index 23ad20d..b5b5983 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminCustomerController.java
@@ -19,7 +19,14 @@ public class AdminCustomerController {
 
     private final UserService userService;
 
-    @ApiOperation("客户列表")
+    @ApiOperation(value = "客户列表", notes = "分页查询小程序注册的C端用户（客户）列表。"
+            + "支持按昵称/手机号/真实姓名关键词搜索，按状态筛选。"
+            + "status取值：ACTIVE=正常 BANNED=已封禁。"
+            + "需要管理员认证。"
+            + "\n\n**关联字典**：\n"
+            + "- user_status（用户状态）：请求参数status和返回字段status（ACTIVE=正常, BANNED=已封禁）\n"
+            + "- gender（性别）：返回字段gender（0=女, 1=男）\n"
+            + "- id_card_type（证件类型）：返回字段idCardType")
     @GetMapping
     public Result<PageResult<CustomerVO>> listCustomers(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -30,14 +37,21 @@ public class AdminCustomerController {
         return Result.success(result);
     }
 
-    @ApiOperation("客户详情")
+    @ApiOperation(value = "客户详情", notes = "获取指定客户的详细信息。"
+            + "\n\n**关联字典**：\n"
+            + "- user_status（用户状态）：返回字段status\n"
+            + "- gender（性别）：返回字段gender\n"
+            + "- id_card_type（证件类型）：返回字段idCardType")
     @GetMapping("/{userId}")
     public Result<CustomerVO> getCustomer(@ApiParam("用户ID") @PathVariable Long userId) {
         CustomerVO customer = userService.getCustomerDetail(userId);
         return Result.success(customer);
     }
 
-    @ApiOperation("封禁客户")
+    @ApiOperation(value = "封禁客户", notes = "封禁指定的C端用户，状态变为BANNED。"
+            + "封禁后该用户无法登录小程序，已有的Token将失效。"
+            + "封禁操作不会删除用户数据，可通过[解封客户]接口恢复。"
+            + "需要管理员认证。")
     @OperationLog(value = "封禁客户", module = "客户管理")
     @PostMapping("/{userId}/ban")
     public Result<Void> banCustomer(@ApiParam("用户ID") @PathVariable Long userId) {
@@ -45,7 +59,9 @@ public class AdminCustomerController {
         return Result.success();
     }
 
-    @ApiOperation("解封客户")
+    @ApiOperation(value = "解封客户", notes = "解封已封禁的C端用户，状态恢复为ACTIVE。"
+            + "解封后用户可正常登录小程序。"
+            + "需要管理员认证。")
     @OperationLog(value = "解封客户", module = "客户管理")
     @PostMapping("/{userId}/unban")
     public Result<Void> unbanCustomer(@ApiParam("用户ID") @PathVariable Long userId) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java
index 5dfa05d..c76c659 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminDesignerController.java
@@ -30,14 +30,18 @@ public class AdminDesignerController {
     private final DesignerProfileService designerProfileService;
     private final DesignerDashboardService designerDashboardService;
 
-    @ApiOperation("获取我的个人资料（已废弃，请使用 /admin/profile/me）")
+    @ApiOperation(value = "获取我的个人资料（已废弃，请使用 /admin/profile/me）", notes = "已废弃接口。"
+            + "\n\n**关联字典**：\n"
+            + "- designer_cert_level（认证等级）：返回字段certLevel（none/bronze/silver/gold/diamond）")
     @GetMapping("/profile")
     public Result<DesignerProfileVO> getMyProfile(HttpServletRequest request) {
         Long adminId = getAdminId(request);
         return Result.success(designerProfileService.getMyProfile(adminId));
     }
 
-    @ApiOperation("更新我的个人资料（已废弃，请使用 PUT /admin/profile/me）")
+    @ApiOperation(value = "更新我的个人资料（已废弃，请使用 PUT /admin/profile/me）",
+            notes = "已废弃接口，请迁移至 PUT /admin/profile/me。\n\n"
+                + "**权限**：需要管理员登录。")
     @PutMapping("/profile")
     public Result<DesignerProfileVO> updateMyProfile(HttpServletRequest request,
                                                       @Valid @RequestBody UpdateDesignerProfileRequest body) {
@@ -45,14 +49,18 @@ public class AdminDesignerController {
         return Result.success(designerProfileService.updateMyProfile(adminId, body));
     }
 
-    @ApiOperation("工作台概览（已废弃，请使用 /admin/profile/dashboard）")
+    @ApiOperation(value = "工作台概览（已废弃，请使用 /admin/profile/dashboard）",
+            notes = "已废弃接口，请迁移至 GET /admin/profile/dashboard。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/dashboard")
     public Result<DesignerDashboardVO> getDashboard(HttpServletRequest request) {
         Long adminId = getAdminId(request);
         return Result.success(designerDashboardService.getDashboard(adminId, "today"));
     }
 
-    @ApiOperation("我的订单列表（已废弃，请使用 /admin/profile/orders）")
+    @ApiOperation(value = "我的订单列表（已废弃，请使用 /admin/profile/orders）", notes = "已废弃接口。"
+            + "\n\n**关联字典**：\n"
+            + "- order_status（订单状态）：请求参数status和返回字段status")
     @GetMapping("/orders")
     public Result<PageResult<Map<String, Object>>> getMyOrders(
             HttpServletRequest request,
@@ -64,7 +72,9 @@ public class AdminDesignerController {
         return Result.success(designerDashboardService.getMyOrders(adminId, page, pageSize, status, keyword));
     }
 
-    @ApiOperation("我的产品列表（已废弃，请使用 /admin/profile/products）")
+    @ApiOperation(value = "我的产品列表（已废弃，请使用 /admin/profile/products）", notes = "已废弃接口。"
+            + "\n\n**关联字典**：\n"
+            + "- product_status（产品状态）：请求参数status和返回字段status")
     @GetMapping("/products")
     public Result<PageResult<Map<String, Object>>> getMyProducts(
             HttpServletRequest request,

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java
index ebe2d88..f6fe95a 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminExploreCategoryController.java
@@ -24,7 +24,9 @@ public class AdminExploreCategoryController {
 
     private final ExploreCategoryService exploreCategoryService;
 
-    @ApiOperation("探索分类列表")
+    @ApiOperation(value = "探索分类列表", notes = "分页查询探索分类列表，支持按关键词和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）")
     @GetMapping
     public Result<PageResult<ExploreCategoryVO>> listCategories(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -35,13 +37,20 @@ public class AdminExploreCategoryController {
         return Result.success(result);
     }
 
-    @ApiOperation("探索分类详情")
+    @ApiOperation(value = "探索分类详情",
+            notes = "获取指定探索分类的详细信息，包括标题、封面图、描述、关联的景区资源列表等。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- common_status（通用状态）：返回字段status（0=禁用, 1=启用）")
     @GetMapping("/{id}")
     public Result<ExploreCategoryDetailVO> getCategory(@ApiParam("分类ID") @PathVariable Long id) {
         return Result.success(exploreCategoryService.getCategory(id));
     }
 
-    @ApiOperation("创建探索分类")
+    @ApiOperation(value = "创建探索分类",
+            notes = "创建新的探索分类，用于小程序探索页面的分类展示。\n"
+                + "可关联多个景区资源，设置封面图和描述文字。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "创建探索分类", module = "探索管理")
     @PostMapping
     public Result<Void> createCategory(@ApiParam("分类创建请求") @Valid @RequestBody ExploreCategoryRequest request,
@@ -51,7 +60,9 @@ public class AdminExploreCategoryController {
         return Result.success();
     }
 
-    @ApiOperation("更新探索分类")
+    @ApiOperation(value = "更新探索分类",
+            notes = "更新指定探索分类的标题、封面图、描述、关联资源、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "更新探索分类", module = "探索管理")
     @PutMapping("/{id}")
     public Result<Void> updateCategory(@ApiParam("分类ID") @PathVariable Long id,
@@ -60,7 +71,10 @@ public class AdminExploreCategoryController {
         return Result.success();
     }
 
-    @ApiOperation("删除探索分类")
+    @ApiOperation(value = "删除探索分类",
+            notes = "删除指定的探索分类（软删除），同时清除关联的资源绑定关系。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序探索页面将不再展示该分类。")
     @OperationLog(value = "删除探索分类", module = "探索管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteCategory(@ApiParam("分类ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java
index 61a2dbb..11e1fdd 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFaqController.java
@@ -26,20 +26,28 @@ public class AdminFaqController {
 
     // ==================== 分类 ====================
 
-    @ApiOperation("分类列表")
+    @ApiOperation(value = "分类列表",
+            notes = "获取所有FAQ分类的完整列表（不分页）。\n"
+                + "每个分类包含名称、排序号、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/categories")
     public Result<List<FaqCategoryVO>> listCategories() {
         return Result.success(faqService.listCategories());
     }
 
-    @ApiOperation("创建分类")
+    @ApiOperation(value = "创建分类",
+            notes = "创建新的FAQ分类，用于对常见问题进行归类。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：分类名称不能重复。")
     @OperationLog(value = "创建FAQ分类", module = "常见问题管理")
     @PostMapping("/categories")
     public Result<FaqCategoryVO> createCategory(@Valid @RequestBody FaqCategoryRequest request) {
         return Result.success(faqService.createCategory(request));
     }
 
-    @ApiOperation("更新分类")
+    @ApiOperation(value = "更新分类",
+            notes = "更新指定FAQ分类的名称、排序号、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "更新FAQ分类", module = "常见问题管理")
     @PutMapping("/categories/{id}")
     public Result<FaqCategoryVO> updateCategory(@ApiParam("分类ID") @PathVariable Long id,
@@ -47,7 +55,10 @@ public class AdminFaqController {
         return Result.success(faqService.updateCategory(id, request));
     }
 
-    @ApiOperation("删除分类")
+    @ApiOperation(value = "删除分类",
+            notes = "删除指定的FAQ分类（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除分类不会删除其下的条目，但条目将变为无分类状态。")
     @OperationLog(value = "删除FAQ分类", module = "常见问题管理")
     @DeleteMapping("/categories/{id}")
     public Result<Void> deleteCategory(@ApiParam("分类ID") @PathVariable Long id) {
@@ -57,21 +68,29 @@ public class AdminFaqController {
 
     // ==================== 条目 ====================
 
-    @ApiOperation("条目列表")
+    @ApiOperation(value = "条目列表",
+            notes = "查询FAQ条目列表，支持按分类ID筛选。\n"
+                + "返回问题标题、回答内容（富文本）、排序号等。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/items")
     public Result<List<FaqItemVO>> listItems(
             @ApiParam("分类ID（可选）") @RequestParam(required = false) Long categoryId) {
         return Result.success(faqService.listItems(categoryId));
     }
 
-    @ApiOperation("创建条目")
+    @ApiOperation(value = "创建条目",
+            notes = "创建一条常见问题，包含问题标题和回答（支持富文本）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：需指定所属分类ID，排序号越小越靠前。")
     @OperationLog(value = "创建FAQ条目", module = "常见问题管理")
     @PostMapping("/items")
     public Result<FaqItemVO> createItem(@Valid @RequestBody FaqItemRequest request) {
         return Result.success(faqService.createItem(request));
     }
 
-    @ApiOperation("更新条目")
+    @ApiOperation(value = "更新条目",
+            notes = "更新指定FAQ条目的问题标题、回答内容、排序号等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "更新FAQ条目", module = "常见问题管理")
     @PutMapping("/items/{id}")
     public Result<FaqItemVO> updateItem(@ApiParam("条目ID") @PathVariable Long id,
@@ -79,7 +98,10 @@ public class AdminFaqController {
         return Result.success(faqService.updateItem(id, request));
     }
 
-    @ApiOperation("删除条目")
+    @ApiOperation(value = "删除条目",
+            notes = "删除指定的FAQ条目（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序FAQ页面将不再展示该条目。")
     @OperationLog(value = "删除FAQ条目", module = "常见问题管理")
     @DeleteMapping("/items/{id}")
     public Result<Void> deleteItem(@ApiParam("条目ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java
index e81218e..5f5117b 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminFrontendConfigController.java
@@ -24,7 +24,9 @@ public class AdminFrontendConfigController {
 
     private final FrontendConfigService frontendConfigService;
 
-    @ApiOperation("配置列表")
+    @ApiOperation(value = "配置列表", notes = "分页查询前端配置列表，支持按关键词、分组和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）")
     @GetMapping
     public Result<PageResult<FrontendConfigVO>> listConfigs(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -35,7 +37,10 @@ public class AdminFrontendConfigController {
         return Result.success(frontendConfigService.listConfigs(page, pageSize, keyword, configGroup, status));
     }
 
-    @ApiOperation("配置列表（不分页）")
+    @ApiOperation(value = "配置列表（不分页）",
+            notes = "获取所有前端配置项的完整列表（不分页），支持按分组和状态筛选。\n"
+                + "适用于需要一次性加载全部配置的场景。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/all")
     public Result<List<FrontendConfigVO>> listAllConfigs(
             @ApiParam("配置分组") @RequestParam(required = false) String configGroup,
@@ -43,25 +48,37 @@ public class AdminFrontendConfigController {
         return Result.success(frontendConfigService.listAllConfigs(configGroup, status));
     }
 
-    @ApiOperation("配置详情")
+    @ApiOperation(value = "配置详情",
+            notes = "根据配置ID获取指定前端配置项的详细信息，包括key、value、分组、描述等。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/{id}")
     public Result<FrontendConfigVO> getConfig(@ApiParam("配置ID") @PathVariable Long id) {
         return Result.success(frontendConfigService.getConfig(id));
     }
 
-    @ApiOperation("按key查询配置")
+    @ApiOperation(value = "按key查询配置",
+            notes = "根据配置键（configKey）获取指定的前端配置项。\n"
+                + "configKey为全局唯一标识，如 app_name、primary_color 等。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/by-key/{key}")
     public Result<FrontendConfigVO> getConfigByKey(@ApiParam("配置键") @PathVariable String key) {
         return Result.success(frontendConfigService.getConfigByKey(key));
     }
 
-    @ApiOperation("获取所有分组")
+    @ApiOperation(value = "获取所有分组",
+            notes = "获取前端配置中所有已使用的分组名称列表。\n"
+                + "用于配置管理页面的分组筛选下拉框。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/groups")
     public Result<List<String>> listGroups() {
         return Result.success(frontendConfigService.listGroups());
     }
 
-    @ApiOperation("创建配置")
+    @ApiOperation(value = "创建配置",
+            notes = "创建新的前端配置项，用于控制前端页面的展示和行为。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：configKey 必须全局唯一，不能与已有配置重复。"
+                + "可通过 sensitive 字段标记是否为敏感配置（敏感配置不会通过公开接口暴露给小程序）。")
     @OperationLog(value = "创建前端配置", module = "前端配置管理")
     @PostMapping
     public Result<FrontendConfigVO> createConfig(
@@ -71,7 +88,10 @@ public class AdminFrontendConfigController {
         return Result.success(frontendConfigService.createConfig(request, adminId));
     }
 
-    @ApiOperation("更新配置")
+    @ApiOperation(value = "更新配置",
+            notes = "更新指定前端配置项的值、分组、描述、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：修改后前端会实时使用新值（如有缓存需等待刷新）。")
     @OperationLog(value = "更新前端配置", module = "前端配置管理")
     @PutMapping("/{id}")
     public Result<FrontendConfigVO> updateConfig(
@@ -80,7 +100,10 @@ public class AdminFrontendConfigController {
         return Result.success(frontendConfigService.updateConfig(id, request));
     }
 
-    @ApiOperation("删除配置")
+    @ApiOperation(value = "删除配置",
+            notes = "删除指定的前端配置项（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后前端将无法获取该配置，可能影响页面展示，请确认无引用后再删除。")
     @OperationLog(value = "删除前端配置", module = "前端配置管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteConfig(@ApiParam("配置ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java
index e174243..6558bc2 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java
@@ -29,7 +29,12 @@ public class AdminProfileController {
     private final FinanceDashboardService financeDashboardService;
     private final MaterialDashboardService materialDashboardService;
 
-    @ApiOperation("获取我的个人资料")
+    @ApiOperation(value = "获取我的个人资料",
+            notes = "获取当前登录管理员的个人资料，根据角色返回不同的资料内容。\n"
+                + "定制师角色会返回认证等级、个人简介、擅长领域等附加信息。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- designer_cert_level（认证等级）：返回字段certLevel（none/bronze/silver/gold/diamond）")
     @GetMapping("/me")
     public Result<ProfileVO> getMyProfile(HttpServletRequest request) {
         Long adminId = getAdminId(request);
@@ -37,7 +42,10 @@ public class AdminProfileController {
         return Result.success(profileService.getProfile(adminId, role));
     }
 
-    @ApiOperation("更新我的个人资料")
+    @ApiOperation(value = "更新我的个人资料",
+            notes = "更新当前登录管理员的个人资料，支持修改昵称、头像、个人简介等。\n"
+                + "定制师角色可额外更新擅长领域、服务区域等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @PutMapping("/me")
     public Result<ProfileVO> updateMyProfile(HttpServletRequest request,
                                               @Valid @RequestBody UpdateDesignerProfileRequest body) {
@@ -46,9 +54,19 @@ public class AdminProfileController {
         return Result.success(profileService.updateProfile(adminId, role, body));
     }
 
-    @ApiOperation("工作台仪表盘（角色分发，支持时间范围）")
+    @ApiOperation(value = "工作台仪表盘（角色分发，支持时间范围）", notes = "根据当前管理员角色返回不同的仪表盘数据。"
+            + "CUSTOMIZER（定制师）：待处理订单数、产品数、评价统计等。"
+            + "SUPER_ADMIN/ADMIN：全局概览（订单、收入、用户增长等）。"
+            + "ROOM_MANAGER（客房管理）：房间分配概览。"
+            + "VEHICLE_MANAGER（车辆管理）：车辆调度概览。"
+            + "FINANCE（财务）：收支统计。"
+            + "MATERIAL_ADMIN（素材管理）：素材库概览。"
+            + "period取值：today=今日 week=本周 month=本月。"
+            + "需要管理员认证。"
+            + "\n\n**关联字典**：\n"
+            + "- order_status（订单状态）：仪表盘中订单统计按状态分组展示")
     @GetMapping("/dashboard")
-    public Result<?> getDashboard(
+    public Result<Object> getDashboard(
             HttpServletRequest request,
             @ApiParam("时间范围: today/week/month") @RequestParam(defaultValue = "today") String period) {
         Long adminId = getAdminId(request);
@@ -72,7 +90,9 @@ public class AdminProfileController {
         }
     }
 
-    @ApiOperation("我的评价列表")
+    @ApiOperation(value = "我的评价列表", notes = "查询当前定制师收到的评价列表，支持按评价等级筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- rating_level（评价等级）：GOOD=好评, MEDIUM=中评, BAD=差评（筛选条件+列表展示）\n")
     @GetMapping("/reviews")
     public Result<PageResult<Map<String, Object>>> getReviews(
             HttpServletRequest request,
@@ -83,7 +103,9 @@ public class AdminProfileController {
         return Result.success(designerDashboardService.getMyReviews(adminId, page, pageSize, ratingLevel));
     }
 
-    @ApiOperation("订单列表")
+    @ApiOperation(value = "订单列表", notes = "查询当前定制师的订单列表，支持按状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- order_status（订单状态）：请求参数status和返回字段status")
     @GetMapping("/orders")
     public Result<PageResult<Map<String, Object>>> getOrders(
             HttpServletRequest request,
@@ -95,7 +117,9 @@ public class AdminProfileController {
         return Result.success(designerDashboardService.getMyOrders(adminId, page, pageSize, status, keyword));
     }
 
-    @ApiOperation("产品列表")
+    @ApiOperation(value = "产品列表", notes = "查询当前定制师的产品列表，支持按状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- product_status（产品状态）：请求参数status和返回字段status")
     @GetMapping("/products")
     public Result<PageResult<Map<String, Object>>> getProducts(
             HttpServletRequest request,

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java
index 7d2e9bc..e6766e3 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminTopicController.java
@@ -23,7 +23,9 @@ public class AdminTopicController {
 
     private final TopicService topicService;
 
-    @ApiOperation("专题列表")
+    @ApiOperation(value = "专题列表", notes = "分页查询探索专题列表，支持按关键词和状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）")
     @GetMapping
     public Result<PageResult<TopicVO>> listTopics(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -34,13 +36,20 @@ public class AdminTopicController {
         return Result.success(result);
     }
 
-    @ApiOperation("专题详情")
+    @ApiOperation(value = "专题详情",
+            notes = "获取指定探索专题的详细信息，包括标题、封面图、描述、关联资源等。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- common_status（通用状态）：返回字段status（0=禁用, 1=启用）")
     @GetMapping("/{id}")
     public Result<TopicVO> getTopic(@ApiParam("专题ID") @PathVariable Long id) {
         return Result.success(topicService.getTopic(id));
     }
 
-    @ApiOperation("创建专题")
+    @ApiOperation(value = "创建专题",
+            notes = "创建新的探索专题，用于小程序探索页面展示主题推荐内容。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：创建时需设置标题、封面图等基本信息。")
     @OperationLog(value = "创建专题", module = "探索专题管理")
     @PostMapping
     public Result<TopicVO> createTopic(@ApiParam("专题创建请求") @Valid @RequestBody TopicRequest request,
@@ -49,7 +58,9 @@ public class AdminTopicController {
         return Result.success(topicService.createTopic(request, adminId));
     }
 
-    @ApiOperation("更新专题")
+    @ApiOperation(value = "更新专题",
+            notes = "更新指定探索专题的标题、封面图、描述、状态等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @OperationLog(value = "更新专题", module = "探索专题管理")
     @PutMapping("/{id}")
     public Result<TopicVO> updateTopic(@ApiParam("专题ID") @PathVariable Long id,
@@ -57,7 +68,10 @@ public class AdminTopicController {
         return Result.success(topicService.updateTopic(id, request));
     }
 
-    @ApiOperation("删除专题")
+    @ApiOperation(value = "删除专题",
+            notes = "删除指定的探索专题（软删除）。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：删除后小程序探索页面将不再展示该专题。")
     @OperationLog(value = "删除专题", module = "探索专题管理")
     @DeleteMapping("/{id}")
     public Result<Void> deleteTopic(@ApiParam("专题ID") @PathVariable Long id) {

`hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java
index 2b3f74a..0344258 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java
@@ -26,7 +26,12 @@ public class AdminUserController {
 
     private final AdminUserService adminUserService;
 
-    @ApiOperation("创建管理员")
+    @ApiOperation(value = "创建管理员", notes = "创建新的后台管理员账号。"
+            + "默认密码为Admin@123456，管理员首次登录后建议修改密码。"
+            + "可通过roleIds分配多个角色，也兼容旧的单角色roleId参数。"
+            + "需要SUPER_ADMIN或ADMIN角色。"
+            + "\n\n**关联字典**：\n"
+            + "- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用\n")
     @OperationLog(value = "创建管理员", module = "管理员管理")
     @PostMapping
     public Result<AdminUser> createAdmin(@ApiParam("创建管理员请求") @Valid @RequestBody CreateAdminRequest request) {
@@ -34,7 +39,9 @@ public class AdminUserController {
         return Result.success(admin);
     }
 
-    @ApiOperation("更新管理员")
+    @ApiOperation(value = "更新管理员", notes = "更新管理员信息，包括用户名、状态、角色分配等。"
+            + "\n\n**关联字典**：\n"
+            + "- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用\n")
     @OperationLog(value = "更新管理员", module = "管理员管理")
     @PutMapping("/{adminId}")
     public Result<AdminUser> updateAdmin(@ApiParam("管理员ID") @PathVariable Long adminId,
@@ -43,7 +50,10 @@ public class AdminUserController {
         return Result.success(admin);
     }
 
-    @ApiOperation("删除管理员")
+    @ApiOperation(value = "删除管理员", notes = "删除指定管理员账号（软删除）。"
+            + "不能删除自己的账号，不能删除SUPER_ADMIN角色的账号（除非操作者也是SUPER_ADMIN）。"
+            + "删除后该管理员的登录状态自动失效。"
+            + "需要SUPER_ADMIN或ADMIN角色。")
     @OperationLog(value = "删除管理员", module = "管理员管理")
     @DeleteMapping("/{adminId}")
     public Result<Void> deleteAdmin(@ApiParam("管理员ID") @PathVariable Long adminId,
@@ -54,7 +64,9 @@ public class AdminUserController {
         return Result.success();
     }
 
-    @ApiOperation("解锁管理员")
+    @ApiOperation(value = "解锁管理员", notes = "解锁因登录失败次数过多而被锁定的管理员账号。"
+            + "管理员连续5次登录失败后账号自动锁定30分钟，此接口可立即解锁。"
+            + "需要SUPER_ADMIN或ADMIN角色。")
     @OperationLog(value = "解锁管理员", module = "管理员管理")
     @PostMapping("/{adminId}/unlock")
     public Result<Void> unlockAdmin(@ApiParam("管理员ID") @PathVariable Long adminId,
@@ -65,7 +77,10 @@ public class AdminUserController {
         return Result.success();
     }
 
-    @ApiOperation("重置密码")
+    @ApiOperation(value = "重置密码", notes = "将指定管理员的密码重置为默认密码（Admin@123456）。"
+            + "用于管理员忘记密码时由上级管理员操作重置。"
+            + "重置后管理员可用默认密码登录，建议立即修改。"
+            + "需要SUPER_ADMIN或ADMIN角色。")
     @OperationLog(value = "重置密码", module = "管理员管理")
     @PostMapping("/{adminId}/reset-password")
     public Result<Void> resetPassword(@ApiParam("管理员ID") @PathVariable Long adminId,
@@ -76,7 +91,10 @@ public class AdminUserController {
         return Result.success();
     }
 
-    @ApiOperation("修改企业微信绑定（支持换绑）")
+    @ApiOperation(value = "修改企业微信绑定（支持换绑）", notes = "为管理员绑定或更换企业微信账号。"
+            + "绑定后管理员可通过企业微信扫码登录，并可接收审批通知。"
+            + "如果目标企微ID已被其他管理员绑定，需设置forceRebind=true强制换绑。"
+            + "需要管理员认证。")
     @OperationLog(value = "修改企业微信绑定", module = "管理员管理")
     @PutMapping("/{adminId}/wechat-binding")
     public Result<Map<String, Object>> updateWechatBinding(
@@ -92,14 +110,21 @@ public class AdminUserController {
         return Result.success(result);
     }
 
-    @ApiOperation("获取管理员详情")
+    @ApiOperation(value = "获取管理员详情", notes = "获取指定管理员的完整信息。"
+            + "\n\n**关联字典**：\n"
+            + "- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用\n")
     @GetMapping("/{adminId}")
     public Result<AdminUser> getAdmin(@ApiParam("管理员ID") @PathVariable Long adminId) {
         AdminUser admin = adminUserService.getAdminById(adminId);
         return Result.success(admin);
     }
 
-    @ApiOperation("管理员列表")
+    @ApiOperation(value = "管理员列表", notes = "分页查询管理员列表，支持按角色、状态、企微绑定状态筛选。"
+            + "status取值：ACTIVE=正常 LOCKED=已锁定 DISABLED=已禁用。"
+            + "wechatBound：true=已绑定企业微信 false=未绑定。"
+            + "需要管理员认证。"
+            + "\n\n**关联字典**：\n"
+            + "- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用（筛选条件+列表展示）\n")
     @GetMapping
     public Result<PageResult<AdminUser>> listAdmins(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,

`hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java
index bf6beb1..84bf6c9 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java
@@ -30,7 +30,10 @@ public class AuthController {
     @Value("${auth.2fa-confirm-enabled:false}")
     private boolean twoFaConfirmEnabled;
 
-    @ApiOperation("管理员登录")
+    @ApiOperation(value = "管理员登录", notes = "管理员通过用户名+密码登录后台管理系统。"
+            + "首次在新设备登录时需要进行企业微信扫码二次验证（2FA），返回needTwoFa=true。"
+            + "登录失败5次后账号将被锁定30分钟。"
+            + "无需认证即可调用。")
     @PostMapping("/login")
     public Result<AdminLoginResponse> login(@ApiParam("管理员登录请求") @Valid @RequestBody AdminLoginRequest request,
                                               HttpServletRequest httpRequest) {
@@ -41,7 +44,10 @@ public class AuthController {
         return Result.success(response);
     }
 
-    @ApiOperation("2FA验证")
+    @ApiOperation(value = "2FA验证", notes = "新设备登录时的企业微信二次验证。"
+            + "管理员登录返回needTwoFa=true后，前端调用此接口提交验证码完成登录。"
+            + "验证通过后设备将被标记为可信设备，后续登录不再需要2FA。"
+            + "无需认证即可调用。")
     @PostMapping("/wechat/verify-2fa")
     public Result<AdminLoginResponse> verifyTwoFa(@ApiParam("管理员ID") @RequestParam Long adminId,
                                                     @ApiParam("2FA验证请求") @Valid @RequestBody TwoFaVerifyRequest request,
@@ -53,7 +59,10 @@ public class AuthController {
         return Result.success(response);
     }
 
-    @ApiOperation("修改密码")
+    @ApiOperation(value = "修改密码", notes = "管理员修改自己的登录密码。"
+            + "需验证旧密码正确后才能设置新密码，新密码须满足复杂度要求（8-128位，含大小写字母和数字）。"
+            + "修改成功后当前Token仍然有效，无需重新登录。"
+            + "需要管理员认证（Token中的adminId）。")
     @OperationLog(value = "修改密码", module = "认证管理")
     @PutMapping("/password")
     public Result<Void> changePassword(HttpServletRequest request,
@@ -63,7 +72,9 @@ public class AuthController {
         return Result.success();
     }
 
-    @ApiOperation("管理员登出")
+    @ApiOperation(value = "管理员登出", notes = "清除管理员的登录状态并使当前Token失效。"
+            + "前端应在登出后清除本地存储的Token和用户信息。"
+            + "需要管理员认证。")
     @PostMapping("/logout")
     public Result<Void> logout(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");
@@ -71,14 +82,20 @@ public class AuthController {
         return Result.success();
     }
 
-    @ApiOperation("生成2FA扫码会话")
+    @ApiOperation(value = "生成2FA扫码会话", notes = "生成企业微信扫码二维码的会话信息，用于新设备二次验证。"
+            + "返回包含qrcodeUrl（二维码链接）和state（会话标识）。"
+            + "前端展示二维码后通过轮询 /2fa/check 接口检查扫码状态。"
+            + "无需认证即可调用（登录流程中使用）。")
     @GetMapping("/2fa/qrcode")
     public Result<Map<String, Object>> generate2FaQrcode(@ApiParam("管理员ID") @RequestParam Long adminId) {
         Map<String, Object> data = adminAuthService.generate2FaQrSession(adminId);
         return Result.success(data);
     }
 
-    @ApiOperation("2FA企微扫码回调")
+    @ApiOperation(value = "2FA企微扫码回调", notes = "企业微信OAuth回调地址，用户扫码授权后微信服务器回调此接口。"
+            + "此接口由微信服务器调用，非前端直接调用。"
+            + "回调成功后将state对应的会话标记为已扫码，前端轮询 /2fa/check 即可获取结果。"
+            + "返回HTML页面（成功/失败提示），不返回JSON。")
     @GetMapping(value = "/2fa/callback", produces = MediaType.TEXT_HTML_VALUE)
     @ResponseBody
     public String handle2FaCallback(@ApiParam("授权码") @RequestParam String code, @ApiParam("会话状态") @RequestParam String state) {
@@ -120,14 +137,19 @@ public class AuthController {
 
     // ==================== WeChat QR Direct Login ====================
 
-    @ApiOperation("生成企业微信扫码登录会话")
+    @ApiOperation(value = "生成企业微信扫码登录会话", notes = "生成企业微信扫码直接登录的会话信息（非2FA验证，而是扫码替代密码登录）。"
+            + "返回包含qrcodeUrl和state。前端展示二维码后通过轮询 /wechat-qr/status 检查登录状态。"
+            + "无需认证即可调用。")
     @GetMapping("/wechat-qr")
     public Result<Map<String, Object>> generateWechatLoginQr() {
         Map<String, Object> data = adminAuthService.generateWechatLoginQrSession();
         return Result.success(data);
     }
 
-    @ApiOperation("企业微信扫码登录回调")
+    @ApiOperation(value = "企业微信扫码登录回调", notes = "企业微信OAuth回调地址，扫码登录授权后微信服务器回调此接口。"
+            + "此接口由微信服务器调用，非前端直接调用。"
+            + "回调后标记会话为已扫码，前端通过轮询 /wechat-qr/status 获取登录结果。"
+            + "返回HTML页面，不返回JSON。")
     @GetMapping(value = "/wechat-qr/callback", produces = MediaType.TEXT_HTML_VALUE)
     @ResponseBody
     public String handleWechatLoginCallback(@ApiParam("授权码") @RequestParam String code, @ApiParam("会话状态") @RequestParam String state) {
@@ -167,7 +189,10 @@ public class AuthController {
         }
     }
 
-    @ApiOperation("查询企业微信扫码登录状态")
+    @ApiOperation(value = "查询企业微信扫码登录状态", notes = "前端轮询此接口检查扫码登录是否完成。"
+            + "返回status字段：PENDING=等待扫码，SCANNED=已扫码登录成功（附带token和用户信息）。"
+            + "建议轮询间隔2秒，超过5分钟未扫码会话自动失效。"
+            + "无需认证即可调用。")
     @GetMapping("/wechat-qr/status")
     public Result<Map<String, Object>> checkWechatLoginStatus(@ApiParam("会话状态") @RequestParam String state,
                                                                 HttpServletRequest httpRequest) {
@@ -178,7 +203,11 @@ public class AuthController {
         return Result.success(data);
     }
 
-    @ApiOperation("手动确认扫码（内网穿透环境workaround，默认关闭）")
+    @ApiOperation(value = "手动确认扫码（内网穿透环境workaround，默认关闭）",
+            notes = "在内网穿透环境下，企微回调可能无法正常到达，此接口作为手动替代方案。\n"
+                + "需在Nacos配置中开启 auth.2fa-confirm-enabled=true 才可使用。\n\n"
+                + "**权限**：无需认证（登录流程中使用）。\n"
+                + "**注意**：生产环境应保持关闭，仅限开发/测试时使用。")
     @PostMapping("/2fa/confirm")
     public Result<Void> confirm2FaScan(@ApiParam("会话状态") @RequestParam String state,
                                         @ApiParam("管理员ID") @RequestParam String adminId,
@@ -195,7 +224,10 @@ public class AuthController {
         return Result.success();
     }
 
-    @ApiOperation("查询2FA扫码状态")
+    @ApiOperation(value = "查询2FA扫码状态", notes = "前端轮询此接口检查2FA扫码验证是否完成。"
+            + "返回status字段：PENDING=等待扫码，SCANNED=已完成验证（附带token和用户信息）。"
+            + "建议轮询间隔2秒，超过5分钟未扫码会话自动失效。"
+            + "无需认证即可调用（登录流程中使用）。")
     @GetMapping("/2fa/check")
     public Result<Map<String, Object>> check2FaStatus(@ApiParam("会话状态") @RequestParam String state,
                                                        HttpServletRequest httpRequest) {
@@ -206,7 +238,10 @@ public class AuthController {
         return Result.success(data);
     }
 
-    @ApiOperation("切换当前角色")
+    @ApiOperation(value = "切换当前角色", notes = "多角色管理员切换当前活跃角色。"
+            + "切换后返回新的Token和角色对应的菜单权限，前端需更新本地Token并刷新菜单。"
+            + "只能切换到该管理员已分配的角色，否则报错。"
+            + "需要管理员认证。")
     @OperationLog(value = "切换角色", module = "认证管理")
     @PostMapping("/switch-role")
     public Result<AdminLoginResponse> switchRole(HttpServletRequest request,
@@ -216,7 +251,10 @@ public class AuthController {
         return Result.success(response);
     }
 
-    @ApiOperation("更新头像")
+    @ApiOperation(value = "更新头像", notes = "管理员更新自己的头像。"
+            + "需先通过文件服务上传图片获取OSS URL和fileId，再调用此接口绑定。"
+            + "旧头像的文件引用会自动解绑。"
+            + "需要管理员认证。")
     @OperationLog(value = "更新头像", module = "认证管理")
     @PutMapping("/avatar")
     public Result<Void> updateAvatar(HttpServletRequest request,
@@ -226,7 +264,9 @@ public class AuthController {
         return Result.success();
     }
 
-    @ApiOperation("获取当前管理员信息")
+    @ApiOperation(value = "获取当前管理员信息", notes = "获取当前登录管理员的完整信息，包括用户名、头像、角色列表、当前角色、菜单权限等。"
+            + "前端页面初始化时调用此接口获取用户信息和权限数据。"
+            + "需要管理员认证。")
     @GetMapping("/info")
     public Result<AdminLoginResponse> getAdminInfo(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");

`hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java
index 0b374f0..79a06b4 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/FavoriteController.java
@@ -22,7 +22,12 @@ public class FavoriteController {
 
     private final FavoriteService favoriteService;
 
-    @ApiOperation("添加收藏")
+    @ApiOperation(value = "添加收藏", notes = "将指定资源添加到当前用户的收藏列表。"
+            + "同一用户对同一资源不可重复收藏，重复收藏会报错。"
+            + "targetType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT/EXPLORE等。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索（请求参数targetType）\n")
     @PostMapping
     public Result<Favorite> addFavorite(HttpServletRequest request,
                                          @ApiParam("收藏请求") @Valid @RequestBody FavoriteRequest favoriteRequest) {
@@ -31,7 +36,11 @@ public class FavoriteController {
         return Result.success(favorite);
     }
 
-    @ApiOperation("收藏列表")
+    @ApiOperation(value = "收藏列表", notes = "分页查询当前用户的所有收藏记录，按收藏时间倒序排列。"
+            + "返回收藏记录的基础信息（不包含资源详情），需前端根据targetType和targetId再查详情。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：返回字段targetType，前端据此判断跳转到哪种资源详情页\n")
     @GetMapping
     public Result<PageResult<Favorite>> listFavorites(HttpServletRequest request,
                                                        @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -41,7 +50,9 @@ public class FavoriteController {
         return Result.success(result);
     }
 
-    @ApiOperation("删除收藏")
+    @ApiOperation(value = "删除收藏", notes = "根据收藏记录ID取消收藏。"
+            + "只能删除自己的收藏记录，删除他人的收藏会报权限错误。"
+            + "需要小程序用户认证。")
     @DeleteMapping("/{favoriteId}")
     public Result<Void> deleteFavorite(HttpServletRequest request,
                                         @ApiParam("收藏ID") @PathVariable Long favoriteId) {

`hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java
index 2616fdc..a24102e 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/FootprintController.java
@@ -22,7 +22,13 @@ public class FootprintController {
 
     private final FootprintService footprintService;
 
-    @ApiOperation("添加足迹")
+    @ApiOperation(value = "添加足迹", notes = "记录用户浏览资源的足迹。"
+            + "同一用户对同一资源多次浏览只保留最新一条记录（更新时间）。"
+            + "resourceType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT等。"
+            + "通常由前端在进入资源详情页时自动调用。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- footprint_resource_type（足迹资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品（请求参数resourceType）\n")
     @PostMapping
     public Result<Footprint> addFootprint(HttpServletRequest request,
                                             @ApiParam("足迹请求") @Valid @RequestBody FootprintRequest footprintRequest) {
@@ -31,7 +37,10 @@ public class FootprintController {
         return Result.success(footprint);
     }
 
-    @ApiOperation("足迹列表")
+    @ApiOperation(value = "足迹列表", notes = "分页查询当前用户的浏览足迹，按浏览时间倒序排列。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- footprint_resource_type（足迹资源类型）：返回字段resourceType，前端据此判断跳转到哪种资源详情页\n")
     @GetMapping
     public Result<PageResult<Footprint>> listFootprints(HttpServletRequest request,
                                                           @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -41,7 +50,9 @@ public class FootprintController {
         return Result.success(result);
     }
 
-    @ApiOperation("删除足迹")
+    @ApiOperation(value = "删除足迹", notes = "根据足迹记录ID删除单条浏览足迹。"
+            + "只能删除自己的足迹记录。"
+            + "需要小程序用户认证。")
     @DeleteMapping("/{footprintId}")
     public Result<Void> deleteFootprint(HttpServletRequest request,
                                           @ApiParam("足迹ID") @PathVariable Long footprintId) {

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java
index 37a5069..bdd7f6d 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java
@@ -22,7 +22,7 @@ import java.util.*;
  * Called by other services via Feign (not exposed via gateway).
  */
 @Slf4j
-@Api(tags = "【内部接口】审批（Feign调用）")
+@Api(tags = "【内部接口】审批（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/wechat")
 @RequiredArgsConstructor
@@ -129,7 +129,11 @@ public class InternalApprovalController {
     @Value("${approval.product.control-ids.reason:}")
     private String controlIdProductReason;
 
-    @ApiOperation("Submit approval to enterprise WeChat OA")
+    @ApiOperation(value = "提交企业微信OA审批", notes = "内部接口，由其他服务通过Feign调用提交企微审批申请。"
+            + "根据templateId自动路由到对应的审批模板（资源上下架/产品上下架/退款申请/退款申诉）。"
+            + "需提供adminId（管理员提交）或wechatUserId（代理提交）。"
+            + "返回企微审批单号spNo，用于后续查询审批状态。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/submit-approval")
     public Result<ApprovalSubmitResultDTO> submitApproval(@RequestBody ApprovalSubmitDTO dto) {
         if (dto.getTemplateId() == null || dto.getTemplateId().isEmpty()) {
@@ -183,7 +187,10 @@ public class InternalApprovalController {
         return Result.success(result);
     }
 
-    @ApiOperation("Revoke a pending approval in enterprise WeChat OA")
+    @ApiOperation(value = "撤销企业微信OA审批", notes = "内部接口，撤销一个待审批的企微OA审批申请。"
+            + "仅PENDING状态的审批可以撤销，已审批的无法撤销。"
+            + "撤销失败不会抛异常（降级处理），业务侧需自行处理状态。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/revoke-approval/{spNo}")
     public Result<Void> revokeApproval(@PathVariable String spNo) {
         if (spNo == null || spNo.isEmpty()) {
@@ -200,7 +207,12 @@ public class InternalApprovalController {
         return Result.success();
     }
 
-    @ApiOperation("Get approval status from enterprise WeChat OA")
+    @ApiOperation(value = "查询企业微信OA审批状态", notes = "内部接口，根据审批单号查询企微审批的详细状态。"
+            + "返回审批状态（spStatus：1=审批中 2=已通过 3=已驳回 4=已撤销）、申请人、表单数据等。"
+            + "用于审批轮询兜底方案（ApprovalPollingService）。"
+            + "不经过Gateway，仅服务间调用。"
+            + "\n\n**关联字典**：\n"
+            + "- approval_sp_status（审批状态）：返回字段spStatus（1=审批中, 2=已通过, 3=已驳回, 4=已撤销）")
     @GetMapping("/approval-status/{spNo}")
     @SuppressWarnings("unchecked")
     public Result<Map<String, Object>> getApprovalStatus(@PathVariable String spNo) {

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java
index c2204f9..df482d7 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBadgeController.java
@@ -13,7 +13,7 @@ import java.util.Map;
  * 徽章内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/badge")
 @RequiredArgsConstructor
@@ -21,7 +21,10 @@ public class InternalBadgeController {
 
     private final BadgeService badgeService;
 
-    @ApiOperation("获取用户徽章数据")
+    @ApiOperation(value = "获取用户徽章数据",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取指定用户的各类未读数和待处理徽章数据（如未读消息数、待付款订单数等）。\n"
+                + "用于小程序个人中心页面的红点/数字徽章展示。")
     @GetMapping
     public Result<Map<String, Object>> getUserBadgeData(@RequestParam Long userId) {
         return Result.success(badgeService.getUserBadgeData(userId));

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java
index 4df5705..b339c1f 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalBannerController.java
@@ -16,7 +16,7 @@ import java.util.List;
  * Banner内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/banner")
 @RequiredArgsConstructor
@@ -24,7 +24,9 @@ public class InternalBannerController {
 
     private final BannerService bannerService;
 
-    @ApiOperation("获取当前有效Banner列表")
+    @ApiOperation(value = "获取当前有效Banner列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取所有状态为启用的Banner列表，按排序号排列，用于小程序首页轮播展示。")
     @GetMapping("/active")
     public Result<List<BannerVO>> listActiveBanners() {
         return Result.success(bannerService.listActiveBanners());

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java
index d38d4a3..dc412e7 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalContactController.java
@@ -16,7 +16,7 @@ import java.util.List;
  * 联系我们内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/contact")
 @RequiredArgsConstructor
@@ -24,7 +24,10 @@ public class InternalContactController {
 
     private final ContactService contactService;
 
-    @ApiOperation("获取当前有效联系方式列表")
+    @ApiOperation(value = "获取当前有效联系方式列表", notes = "内部接口，获取所有状态为上线的联系方式。"
+            + "不经过Gateway，仅服务间调用。"
+            + "\n\n**关联字典**：\n"
+            + "- contact_channel_type（联系渠道类型）：返回字段channelType（ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询）\n")
     @GetMapping("/active")
     public Result<List<ContactVO>> listActiveContacts() {
         return Result.success(contactService.listActiveContacts());

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java
index 969a9d2..f96ec05 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalDesignerController.java
@@ -14,7 +14,7 @@ import java.util.List;
  * C端定制师内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/designer")
 @RequiredArgsConstructor
@@ -22,20 +22,28 @@ public class InternalDesignerController {
 
     private final DesignerService designerService;
 
-    @ApiOperation("定制师列表")
+    @ApiOperation(value = "定制师列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "分页获取已上线的定制师列表，用于小程序定制师展示页面。\n"
+                + "返回定制师头像、昵称、认证等级、擅长领域等信息。")
     @GetMapping
     public Result<List<DesignerVO>> listDesigners(@RequestParam(defaultValue = "1") int page,
                                                    @RequestParam(defaultValue = "10") int limit) {
         return Result.success(designerService.listDesigners(page, limit));
     }
 
-    @ApiOperation("推荐定制师")
+    @ApiOperation(value = "推荐定制师",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取一位推荐定制师，用于小程序首页推荐位展示。\n"
+                + "推荐逻辑由后端按权重排序选取。")
     @GetMapping("/featured")
     public Result<DesignerVO> getFeaturedDesigner() {
         return Result.success(designerService.getFeaturedDesigner());
     }
 
-    @ApiOperation("定制师详情")
+    @ApiOperation(value = "定制师详情",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取指定定制师的详细信息，包括个人简介、擅长领域、服务案例等。")
     @GetMapping("/{id}")
     public Result<DesignerVO> getDesignerDetail(@PathVariable Long id) {
         return Result.success(designerService.getDesignerDetail(id));

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java
index 1e7bf8d..02ea651 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalExploreCategoryController.java
@@ -26,7 +26,7 @@ import java.util.stream.Collectors;
  * 探索分类内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "探索分类小程序接口")
+@Api(tags = "探索分类小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/explore")
 @RequiredArgsConstructor
@@ -38,7 +38,10 @@ public class InternalExploreCategoryController {
     private final FavoriteService favoriteService;
     private final UserLikeService userLikeService;
 
-    @ApiOperation("获取上线探索分类列表")
+    @ApiOperation(value = "获取上线探索分类列表", notes = "内部接口，获取已上线的探索分类列表，支持排序。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：仅返回status=1（启用）的分类\n"
+            + "- explore_sort_type（排序方式）：请求参数sortType（comprehensive=综合, newest=最新, hottest=最热）")
     @GetMapping("/active")
     public Result<PageResult<ExploreCategoryVO>> listActive(
             @ApiParam("排序方式：comprehensive=综合 newest=最新 hottest=最热") @RequestParam(defaultValue = "comprehensive") String sortType,
@@ -47,7 +50,10 @@ public class InternalExploreCategoryController {
         return Result.success(exploreCategoryService.listActive(sortType, page, pageSize));
     }
 
-    @ApiOperation("获取探索分类详情（自动增加浏览量）")
+    @ApiOperation(value = "获取探索分类详情（自动增加浏览量）",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取指定分类的详细信息，同时自动增加浏览量计数。\n"
+                + "如果传入 X-User-Id 请求头，还会返回当前用户的点赞和收藏状态。")
     @GetMapping("/{id}")
     public Result<ExploreCategoryDetailVO> getActiveDetail(
             @ApiParam("分类ID") @PathVariable Long id,
@@ -65,14 +71,19 @@ public class InternalExploreCategoryController {
         return Result.success(exploreCategoryService.getActiveDetail(id, isLiked, isFavorited));
     }
 
-    @ApiOperation("增加浏览量")
+    @ApiOperation(value = "增加浏览量",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "手动增加指定探索分类的浏览量计数（+1）。")
     @PostMapping("/{id}/view")
     public Result<Void> incrementViewCount(@ApiParam("分类ID") @PathVariable Long id) {
         exploreCategoryService.incrementViewCount(id);
         return Result.success();
     }
 
-    @ApiOperation("切换收藏状态")
+    @ApiOperation(value = "切换收藏状态",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "切换用户对指定探索分类的收藏状态：已收藏则取消，未收藏则添加。\n"
+                + "返回 true=已收藏，false=已取消收藏。同时更新分类的收藏计数。")
     @PostMapping("/{id}/favorite")
     public Result<Boolean> toggleFavorite(
             @ApiParam("分类ID") @PathVariable Long id,
@@ -101,7 +112,9 @@ public class InternalExploreCategoryController {
         }
     }
 
-    @ApiOperation("检查是否已收藏")
+    @ApiOperation(value = "检查是否已收藏",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "检查用户是否已收藏指定的探索分类，返回 true/false。")
     @GetMapping("/{id}/favorite/check")
     public Result<Boolean> checkFavorite(
             @ApiParam("分类ID") @PathVariable Long id,
@@ -109,7 +122,10 @@ public class InternalExploreCategoryController {
         return Result.success(favoriteService.checkFavorite(userId, TARGET_TYPE_EXPLORE, id));
     }
 
-    @ApiOperation("切换点赞状态")
+    @ApiOperation(value = "切换点赞状态",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "切换用户对指定探索分类的点赞状态：已点赞则取消，未点赞则添加。\n"
+                + "返回 true=已点赞，false=已取消。同时更新分类的点赞计数。")
     @PostMapping("/{id}/like")
     public Result<Boolean> toggleLike(
             @ApiParam("分类ID") @PathVariable Long id,
@@ -119,7 +135,9 @@ public class InternalExploreCategoryController {
         return Result.success(liked);
     }
 
-    @ApiOperation("检查是否已点赞")
+    @ApiOperation(value = "检查是否已点赞",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "检查用户是否已点赞指定的探索分类，返回 true/false。")
     @GetMapping("/{id}/like/check")
     public Result<Boolean> checkLike(
             @ApiParam("分类ID") @PathVariable Long id,
@@ -127,7 +145,10 @@ public class InternalExploreCategoryController {
         return Result.success(userLikeService.checkLike(userId, TARGET_TYPE_EXPLORE, id));
     }
 
-    @ApiOperation("获取同分类的景区资源列表")
+    @ApiOperation(value = "获取同分类的景区资源列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "根据景区ID查找与其同一探索分类下的其他景区资源，用于'相关推荐'展示。\n"
+                + "返回资源ID、名称、描述、封面图等基本信息。")
     @GetMapping("/related-scenic")
     public Result<List<Map<String, Object>>> getRelatedScenic(
             @ApiParam("景区ID") @RequestParam Long scenicId,

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java
index 90d24df..e00222c 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFaqController.java
@@ -12,7 +12,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
-@Api(tags = "【内部接口】常见问题（Feign调用）")
+@Api(tags = "【内部接口】常见问题（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/faq")
 @RequiredArgsConstructor
@@ -20,7 +20,9 @@ public class InternalFaqController {
 
     private final FaqService faqService;
 
-    @ApiOperation("获取所有启用的FAQ（含分类和条目）")
+    @ApiOperation(value = "获取所有启用的FAQ（含分类和条目）",
+            notes = "内部服务间调用接口，由其他微服务通过 Feign 调用。\n"
+                + "获取所有状态为启用的FAQ分类及其下属条目，按排序号排列。")
     @GetMapping("/all")
     public Result<List<FaqCategoryVO>> getAllActiveFaq() {
         return Result.success(faqService.getAllActiveFaq());

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java
index 1f32c3b..4976f91 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalFrontendConfigController.java
@@ -14,7 +14,7 @@ import java.util.List;
  * 前端配置内部接口（仅供其他服务通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "【内部接口】前端配置（Feign调用）")
+@Api(tags = "【内部接口】前端配置（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/frontend-config")
 @RequiredArgsConstructor
@@ -22,32 +22,42 @@ public class InternalFrontendConfigController {
 
     private final FrontendConfigService frontendConfigService;
 
-    @ApiOperation("获取所有启用的前端配置")
+    @ApiOperation(value = "获取所有启用的前端配置",
+            notes = "内部服务间调用接口，由其他微服务通过 Feign 调用。\n"
+                + "获取所有状态为启用的前端配置项列表（含敏感配置）。")
     @GetMapping("/all")
     public Result<List<FrontendConfigVO>> listAllActiveConfigs() {
         return Result.success(frontendConfigService.listAllActiveConfigs());
     }
 
-    @ApiOperation("按分组获取启用的配置")
+    @ApiOperation(value = "按分组获取启用的配置",
+            notes = "内部服务间调用接口，由其他微服务通过 Feign 调用。\n"
+                + "按配置分组名获取该分组下所有已启用的配置项。")
     @GetMapping("/group/{group}")
     public Result<List<FrontendConfigVO>> listActiveConfigsByGroup(@PathVariable String group) {
         return Result.success(frontendConfigService.listActiveConfigsByGroup(group));
     }
 
-    @ApiOperation("按key获取单个配置")
+    @ApiOperation(value = "按key获取单个配置",
+            notes = "内部服务间调用接口，由其他微服务通过 Feign 调用。\n"
+                + "根据 configKey 获取单个已启用的配置项，不存在则返回错误。")
     @GetMapping("/key/{key}")
     public Result<FrontendConfigVO> getActiveConfigByKey(@PathVariable String key) {
         FrontendConfigVO vo = frontendConfigService.getActiveConfigByKey(key);
         return vo != null ? Result.success(vo) : Result.error("配置项不存在");
     }
 
-    @ApiOperation("获取所有非敏感的前端配置（供小程序使用）")
+    @ApiOperation(value = "获取所有非敏感的前端配置（供小程序使用）",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取所有已启用且非敏感（sensitive=false）的配置项，安全地暴露给小程序C端。")
     @GetMapping("/public")
     public Result<List<FrontendConfigVO>> listPublicConfigs() {
         return Result.success(frontendConfigService.listPublicConfigs());
     }
 
-    @ApiOperation("按分组获取非敏感配置（供小程序使用）")
+    @ApiOperation(value = "按分组获取非敏感配置（供小程序使用）",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "按分组获取非敏感配置，过滤掉标记为敏感的配置项。")
     @GetMapping("/public/group/{group}")
     public Result<List<FrontendConfigVO>> listPublicConfigsByGroup(@PathVariable String group) {
         return Result.success(frontendConfigService.listPublicConfigsByGroup(group));

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java
index aba407f..a14b558 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLikeController.java
@@ -14,7 +14,7 @@ import java.util.*;
  * 通用点赞内部接口（供 hl-mp-service BFF 通过 Feign 调用）
  * 支持任意资源类型：REVIEW, EXPLORE, GUIDE 等
  */
-@Api(tags = "【内部接口】通用点赞（Feign调用）")
+@Api(tags = "【内部接口】通用点赞（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/like")
 @RequiredArgsConstructor
@@ -22,7 +22,9 @@ public class InternalLikeController {
 
     private final UserLikeService userLikeService;
 
-    @ApiOperation("切换点赞状态（通用）")
+    @ApiOperation(value = "切换点赞状态（通用）", notes = "内部接口，切换用户对指定资源的点赞状态。"
+            + "\n\n**关联字典**：\n"
+            + "- like_target_type（点赞目标类型）：请求参数targetType（REVIEW=评价, EXPLORE=探索, GUIDE=攻略）")
     @PostMapping("/toggle")
     public Result<Map<String, Object>> toggleLike(
             @ApiParam("目标类型") @RequestParam String targetType,
@@ -36,7 +38,9 @@ public class InternalLikeController {
         return Result.success(data);
     }
 
-    @ApiOperation("检查是否已点赞（通用）")
+    @ApiOperation(value = "检查是否已点赞（通用）", notes = "内部接口，检查用户是否已点赞指定资源。"
+            + "\n\n**关联字典**：\n"
+            + "- like_target_type（点赞目标类型）：请求参数targetType（REVIEW=评价, EXPLORE=探索, GUIDE=攻略）")
     @GetMapping("/check")
     public Result<Boolean> checkLike(
             @ApiParam("目标类型") @RequestParam String targetType,
@@ -45,7 +49,9 @@ public class InternalLikeController {
         return Result.success(userLikeService.checkLike(userId, targetType, targetId));
     }
 
-    @ApiOperation("批量检查是否已点赞（接受字符串ID，避免JS大数精度丢失）")
+    @ApiOperation(value = "批量检查是否已点赞（接受字符串ID，避免JS大数精度丢失）", notes = "内部接口，批量检查用户是否已点赞指定资源列表。"
+            + "\n\n**关联字典**：\n"
+            + "- like_target_type（点赞目标类型）：请求参数targetType（REVIEW=评价, EXPLORE=探索, GUIDE=攻略）")
     @PostMapping("/batch-check")
     public Result<List<String>> batchCheckLiked(
             @ApiParam("目标类型") @RequestParam String targetType,

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java
index 124fb4f..179904b 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalLoginLogController.java
@@ -24,7 +24,7 @@ import java.util.stream.Collectors;
  * Internal endpoint for monitor-service to query login logs.
  * NOT exposed via gateway.
  */
-@Api(tags = "【内部接口】登录日志（Feign调用）")
+@Api(tags = "【内部接口】登录日志（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal")
 @RequiredArgsConstructor
@@ -35,7 +35,14 @@ public class InternalLoginLogController {
 
     private static final DateTimeFormatter FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
 
-    @ApiOperation("Query login logs")
+    @ApiOperation(value = "查询登录日志", notes = "内部接口，供hl-monitor-service通过Feign查询管理员登录日志。"
+            + "支持按管理员ID、登录状态、时间范围筛选。"
+            + "status取值：SUCCESS=登录成功 FAILED=登录失败。"
+            + "时间格式：yyyy-MM-dd HH:mm:ss。"
+            + "不经过Gateway，仅服务间调用。"
+            + "\n\n**关联字典**：\n"
+            + "- login_status（登录状态）：请求参数status和返回字段status（SUCCESS=成功, FAILED=失败）\n"
+            + "- login_method（登录方式）：返回字段loginMethod（PASSWORD=密码, WECHAT_QR=企微扫码, TWO_FA=二次验证）")
     @GetMapping("/login-logs")
     public Result<PageResult<LoginLogVO>> queryLoginLogs(
             @RequestParam(defaultValue = "1") int page,

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java
index a8f1de8..8e53118 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpCommonController.java
@@ -11,7 +11,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/common")
 @RequiredArgsConstructor
@@ -19,19 +19,26 @@ public class InternalMpCommonController {
 
     private final CommonService commonService;
 
-    @ApiOperation("应用配置")
+    @ApiOperation(value = "应用配置",
+            notes = "内部服务间调用接口，由 hl-mp-service 调用。\n"
+                + "获取小程序应用的基础配置信息，如版本号、客服电话等。")
     @GetMapping("/config")
     public Result<Map<String, Object>> getConfig() {
         return Result.success(commonService.getConfig());
     }
 
-    @ApiOperation("FAQ列表")
+    @ApiOperation(value = "FAQ列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 调用。\n"
+                + "获取所有启用的FAQ分类及其条目，用于小程序帮助中心页面展示。")
     @GetMapping("/faq")
     public Result<List<Map<String, Object>>> listFaq() {
         return Result.success(commonService.listFaq());
     }
 
-    @ApiOperation("提交反馈")
+    @ApiOperation(value = "提交反馈",
+            notes = "内部服务间调用接口，由 hl-mp-service 调用。\n"
+                + "提交用户反馈意见，包括反馈内容、联系方式等。\n"
+                + "需传入 userId 参数标识提交反馈的用户。")
     @PostMapping("/feedback")
     public Result<Void> submitFeedback(@RequestParam Long userId,
                                         @RequestBody UserFeedback feedback) {
@@ -39,13 +46,18 @@ public class InternalMpCommonController {
         return Result.success(null);
     }
 
-    @ApiOperation("获取协议文本")
+    @ApiOperation(value = "获取协议文本",
+            notes = "内部服务间调用接口，由 hl-mp-service 调用。\n"
+                + "根据协议类型（如 user_agreement、privacy_policy）获取协议的富文本内容。\n"
+                + "用于小程序协议详情页面展示。")
     @GetMapping("/agreement/{type}")
     public Result<Map<String, Object>> getAgreement(@PathVariable String type) {
         return Result.success(commonService.getAgreement(type));
     }
 
-    @ApiOperation("获取所有已上线协议列表")
+    @ApiOperation(value = "获取所有已上线协议列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 调用。\n"
+                + "获取所有状态为启用的协议列表，用于小程序注册/登录时展示需要同意的协议链接。")
     @GetMapping("/agreement/list")
     public Result<List<Map<String, Object>>> listActiveAgreements() {
         return Result.success(commonService.listActiveAgreements());

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java
index e634ded..6028ac3 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpDictController.java
@@ -19,7 +19,7 @@ import java.util.stream.Collectors;
  * C端字典内部接口(仅供 hl-mp-service BFF 通过 Feign 调用)
  * 不经过认证拦截器(/internal/** 已排除)
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/dict")
 @RequiredArgsConstructor
@@ -27,7 +27,9 @@ public class InternalMpDictController {
 
     private final SysDictService sysDictService;
 
-    @ApiOperation("获取所有字典数据(C端小程序)")
+    @ApiOperation(value = "获取所有字典数据(C端小程序)", notes = "内部接口，供hl-mp-service通过Feign获取小程序可用的字典数据。"
+            + "返回格式：[{dictType, dictName, dataList}]，与管理端字典数据格式一致。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/all")
     public Result<List<Map<String, Object>>> getAllDict() {
         List<DictVO> dictList = sysDictService.getAllDictForMiniApp();
@@ -44,7 +46,8 @@ public class InternalMpDictController {
         return Result.success(result);
     }
 
-    @ApiOperation("按字典类型获取字典数据列表")
+    @ApiOperation(value = "按字典类型获取字典数据列表", notes = "内部接口，根据字典类型编码（如order_status）获取该类型下的所有字典数据项。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/type/{dictType}")
     public Result<List<SysDictData>> getDictDataByType(
             @ApiParam("字典类型编码") @PathVariable String dictType) {

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java
index 4921435..f32737c 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpMessageController.java
@@ -14,7 +14,7 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
-@Api(tags = "小程序消息接口")
+@Api(tags = "小程序消息接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/message")
 @RequiredArgsConstructor
@@ -22,19 +22,32 @@ public class InternalMpMessageController {
 
     private final UserMessageService userMessageService;
 
-    @ApiOperation("消息分类列表（含未读数和最新消息预览）")
+    @ApiOperation(value = "消息分类列表（含未读数和最新消息预览）", notes = "获取用户的消息分类汇总信息。"
+            + "每个分类返回：分类名称、未读消息数、最新一条消息的标题和时间。"
+            + "用于消息中心首页展示各分类入口。"
+            + "内部接口，由hl-mp-service通过Feign调用。"
+            + "\n\n**关联字典**：\n"
+            + "- message_category（消息分类）：返回字段code（ORDER=订单消息, TRIP=行程消息, SYSTEM=系统消息, PROMO=营销消息）")
     @GetMapping("/categories")
     public Result<List<CategorySummaryVO>> getCategories(@RequestParam("userId") Long userId) {
         return Result.success(userMessageService.getCategorySummaries(userId));
     }
 
-    @ApiOperation("消息摘要（兼容旧接口）")
+    @ApiOperation(value = "消息摘要（兼容旧接口）",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "功能同 /categories 接口，保留用于向后兼容旧版本小程序。")
     @GetMapping("/summary")
     public Result<List<CategorySummaryVO>> getSummary(@RequestParam("userId") Long userId) {
         return Result.success(userMessageService.getCategorySummaries(userId));
     }
 
-    @ApiOperation("分类内消息列表（进入后自动标记已读）")
+    @ApiOperation(value = "分类内消息列表（进入后自动标记已读）", notes = "分页查询指定分类下的消息列表，按时间倒序排列。"
+            + "进入该分类后自动将该分类的所有消息标记为已读。"
+            + "categoryCode参数支持旧参数名category（向后兼容）。"
+            + "内部接口，由hl-mp-service通过Feign调用。"
+            + "\n\n**关联字典**：\n"
+            + "- message_category（消息分类）：请求参数categoryCode（ORDER=订单消息, TRIP=行程消息, SYSTEM=系统消息, PROMO=营销消息）\n"
+            + "- message_biz_type（关联业务类型）：返回字段bizType（ORDER=订单, REFUND=退款, CONTRACT=合同）")
     @GetMapping("/list")
     public Result<PageResult<UserMessageVO>> listMessages(
             @RequestParam("userId") Long userId,
@@ -47,7 +60,9 @@ public class InternalMpMessageController {
         return Result.success(userMessageService.listMessages(userId, code, page, pageSize));
     }
 
-    @ApiOperation("获取总未读数")
+    @ApiOperation(value = "获取总未读数", notes = "获取用户所有分类的未读消息总数。"
+            + "返回{count: N}格式，用于小程序Tab栏消息角标显示。"
+            + "内部接口，由hl-mp-service通过Feign调用。")
     @GetMapping("/unread-count")
     public Result<Map<String, Integer>> getUnreadCount(@RequestParam("userId") Long userId) {
         Map<String, Integer> result = new HashMap<>();
@@ -55,7 +70,10 @@ public class InternalMpMessageController {
         return Result.success(result);
     }
 
-    @ApiOperation("全部标记已读")
+    @ApiOperation(value = "全部标记已读", notes = "将消息标记为已读。"
+            + "如果传入categoryCode，则只标记该分类下的消息为已读。"
+            + "如果不传categoryCode，则标记所有消息为已读。"
+            + "内部接口，由hl-mp-service通过Feign调用。")
     @PutMapping("/read-all")
     public Result<Void> markAllRead(
             @RequestParam("userId") Long userId,
@@ -70,7 +88,9 @@ public class InternalMpMessageController {
         return Result.success(null);
     }
 
-    @ApiOperation("标记已读")
+    @ApiOperation(value = "标记已读",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "将单条消息标记为已读（兼容旧接口，实际已被分类级别标记替代）。")
     @PutMapping("/{id}/read")
     public Result<Void> markRead(
             @RequestParam("userId") Long userId,
@@ -79,7 +99,9 @@ public class InternalMpMessageController {
         return Result.success(null);
     }
 
-    @ApiOperation("删除消息")
+    @ApiOperation(value = "删除消息",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "删除指定的用户消息记录，删除后不可恢复。")
     @DeleteMapping("/{id}")
     public Result<Void> deleteMessage(
             @RequestParam("userId") Long userId,

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java
index 69c0674..67190a9 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalMpUserController.java
@@ -22,7 +22,7 @@ import java.util.Map;
  * C端用户内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/user")
 @RequiredArgsConstructor
@@ -37,26 +37,37 @@ public class InternalMpUserController {
 
     // ==================== Auth ====================
 
-    @ApiOperation("发送短信验证码")
+    @ApiOperation(value = "发送短信验证码",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "向指定手机号发送6位数字短信验证码，有效期5分钟，60秒内不可重复发送。")
     @PostMapping("/sms/send")
     public Result<Void> sendSmsCode(@Valid @RequestBody SendSmsRequest request) {
         smsService.sendVerificationCode(request.getPhone());
         return Result.success();
     }
 
-    @ApiOperation("短信登录")
+    @ApiOperation(value = "短信登录",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "小程序用户通过手机号+短信验证码登录，首次登录自动注册。\n"
+                + "返回JWT Token和用户基本信息。")
     @PostMapping("/login/sms")
     public Result<LoginResponse> loginBySms(@Valid @RequestBody SmsLoginRequest request) {
         return Result.success(userService.loginBySms(request));
     }
 
-    @ApiOperation("微信登录")
+    @ApiOperation(value = "微信登录",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "小程序用户通过微信授权码（wx.login获取的code）登录，首次登录自动注册。\n"
+                + "返回JWT Token和用户基本信息，含 needProfile 字段标识是否需要补全资料。")
     @PostMapping("/login")
     public Result<LoginResponse> login(@Valid @RequestBody LoginRequest request) {
         return Result.success(userService.login(request));
     }
 
-    @ApiOperation("获取用户信息")
+    @ApiOperation(value = "获取用户信息", notes = "内部接口，获取用户个人资料，含真实手机号。"
+            + "\n\n**关联字典**：\n"
+            + "- gender（性别）：返回字段gender\n"
+            + "- id_card_type（证件类型）：返回字段idCardType")
     @GetMapping("/profile")
     public Result<UserVO> getProfile(@RequestParam Long userId) {
         UserVO vo = userService.getProfile(userId);
@@ -65,21 +76,31 @@ public class InternalMpUserController {
         return Result.success(vo);
     }
 
-    @ApiOperation("更新用户信息")
+    @ApiOperation(value = "更新用户信息",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "更新用户个人资料，包括昵称、头像、性别、实名信息等。\n"
+                + "首次补全资料时 realName/idCardType/idCardNo 为必填。\n\n"
+                + "**关联字典**：\n"
+                + "- gender（性别）：请求字段gender\n"
+                + "- id_card_type（证件类型）：请求字段idCardType")
     @PutMapping("/profile")
     public Result<UserVO> updateProfile(@RequestParam Long userId,
                                        @Valid @RequestBody UpdateProfileRequest request) {
         return Result.success(userService.updateProfile(userId, request));
     }
 
-    @ApiOperation("用户登出")
+    @ApiOperation(value = "用户登出",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "清除指定用户的登录状态，使Token失效。")
     @PostMapping("/logout")
     public Result<Void> logout(@RequestParam Long userId) {
         userService.logout(userId);
         return Result.success();
     }
 
-    @ApiOperation("注销账号")
+    @ApiOperation(value = "注销账号",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "永久注销用户账号（软删除），注销后该手机号可重新注册。")
     @DeleteMapping("/account")
     public Result<Void> deleteAccount(@RequestParam Long userId) {
         userService.deleteAccount(userId);
@@ -88,14 +109,18 @@ public class InternalMpUserController {
 
     // ==================== Favorite ====================
 
-    @ApiOperation("添加收藏")
+    @ApiOperation(value = "添加收藏", notes = "内部接口，为用户添加收藏。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：请求参数targetType（SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索）")
     @PostMapping("/favorite")
     public Result<Favorite> addFavorite(@RequestParam Long userId,
                                        @Valid @RequestBody FavoriteRequest request) {
         return Result.success(favoriteService.addFavorite(userId, request));
     }
 
-    @ApiOperation("收藏列表")
+    @ApiOperation(value = "收藏列表", notes = "内部接口，获取用户收藏列表。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：请求参数targetType和返回字段targetType（SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索）")
     @GetMapping("/favorite")
     public Result<PageResult<Favorite>> listFavorites(@RequestParam Long userId,
                                                      @RequestParam(required = false) String targetType,
@@ -104,7 +129,9 @@ public class InternalMpUserController {
         return Result.success(favoriteService.listFavorites(userId, targetType, page, pageSize));
     }
 
-    @ApiOperation("检查是否已收藏")
+    @ApiOperation(value = "检查是否已收藏", notes = "内部接口，检查用户是否已收藏指定资源。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：请求参数targetType")
     @GetMapping("/favorite/check")
     public Result<Boolean> checkFavorite(@RequestParam Long userId,
                                         @RequestParam String targetType,
@@ -112,7 +139,9 @@ public class InternalMpUserController {
         return Result.success(favoriteService.checkFavorite(userId, targetType, targetId));
     }
 
-    @ApiOperation("批量删除收藏")
+    @ApiOperation(value = "批量删除收藏",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "根据收藏记录ID列表批量删除用户的收藏记录。")
     @DeleteMapping("/favorite/batch")
     public Result<Void> batchDeleteFavorites(@RequestParam Long userId,
                                              @RequestBody List<Long> ids) {
@@ -120,7 +149,9 @@ public class InternalMpUserController {
         return Result.success();
     }
 
-    @ApiOperation("按目标取消收藏")
+    @ApiOperation(value = "按目标取消收藏", notes = "内部接口，按目标类型和ID取消收藏。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：请求参数targetType")
     @DeleteMapping("/favorite/by-target")
     public Result<Void> deleteFavoriteByTarget(@RequestParam Long userId,
                                                @RequestParam String targetType,
@@ -129,7 +160,9 @@ public class InternalMpUserController {
         return Result.success();
     }
 
-    @ApiOperation("取消收藏")
+    @ApiOperation(value = "取消收藏",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "根据收藏记录ID删除单条收藏记录。")
     @DeleteMapping("/favorite/{id}")
     public Result<Void> deleteFavorite(@RequestParam Long userId, @PathVariable Long id) {
         favoriteService.deleteFavorite(userId, id);
@@ -138,14 +171,18 @@ public class InternalMpUserController {
 
     // ==================== Footprint ====================
 
-    @ApiOperation("记录足迹")
+    @ApiOperation(value = "记录足迹", notes = "内部接口，记录用户浏览足迹。"
+            + "\n\n**关联字典**：\n"
+            + "- footprint_resource_type（足迹资源类型）：请求参数resourceType（SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品）")
     @PostMapping("/footprint")
     public Result<Footprint> addFootprint(@RequestParam Long userId,
                                          @Valid @RequestBody FootprintRequest request) {
         return Result.success(footprintService.addFootprint(userId, request));
     }
 
-    @ApiOperation("足迹列表")
+    @ApiOperation(value = "足迹列表", notes = "内部接口，获取用户足迹列表。"
+            + "\n\n**关联字典**：\n"
+            + "- footprint_resource_type（足迹资源类型）：请求参数resourceType和返回字段resourceType（SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品）")
     @GetMapping("/footprint")
     public Result<PageResult<Footprint>> listFootprints(@RequestParam Long userId,
                                                        @RequestParam(required = false) String resourceType,
@@ -154,7 +191,9 @@ public class InternalMpUserController {
         return Result.success(footprintService.listFootprints(userId, resourceType, page, pageSize));
     }
 
-    @ApiOperation("批量删除足迹")
+    @ApiOperation(value = "批量删除足迹",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "根据足迹记录ID列表批量删除用户的浏览足迹。")
     @DeleteMapping("/footprint/batch")
     public Result<Void> batchDeleteFootprints(@RequestParam Long userId,
                                               @RequestBody List<Long> ids) {
@@ -162,7 +201,9 @@ public class InternalMpUserController {
         return Result.success();
     }
 
-    @ApiOperation("删除足迹")
+    @ApiOperation(value = "删除足迹",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "根据足迹记录ID删除单条浏览足迹。")
     @DeleteMapping("/footprint/{id}")
     public Result<Void> deleteFootprint(@RequestParam Long userId, @PathVariable Long id) {
         footprintService.deleteFootprint(userId, id);
@@ -171,26 +212,45 @@ public class InternalMpUserController {

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java
index df5bc72..581cc22 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalOrderUserController.java
@@ -17,7 +17,7 @@ import java.util.Map;
 /**
  * Internal API for order service
  */
-@Api(tags = "【内部接口】订单用户（Feign调用）")
+@Api(tags = "【内部接口】订单用户（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/order/user")
 @RequiredArgsConstructor
@@ -25,7 +25,10 @@ public class InternalOrderUserController {
 
     private final UserService userService;
 
-    @ApiOperation("获取用户基本信息（供订单服务查询使用）")
+    @ApiOperation(value = "获取用户基本信息（供订单服务查询使用）",
+            notes = "内部服务间调用接口，由 hl-order-service 通过 Feign 调用。\n"
+                + "根据 userId 获取用户基本信息（userId、realName、phone），用于订单详情展示。\n"
+                + "**注意**：返回的手机号为真实手机号（未脱敏）。")
     @GetMapping("/info")
     public Result<Map<String, Object>> getUserInfo(@RequestParam Long userId) {
         User user = userService.getById(userId);

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java
index fba4363..e432e26 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalTopicController.java
@@ -16,7 +16,7 @@ import java.util.List;
  * 探索专题内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/topic")
 @RequiredArgsConstructor
@@ -24,7 +24,9 @@ public class InternalTopicController {
 
     private final TopicService topicService;
 
-    @ApiOperation("获取当前有效专题列表")
+    @ApiOperation(value = "获取当前有效专题列表",
+            notes = "内部服务间调用接口，由 hl-mp-service 通过 Feign 调用。\n"
+                + "获取所有状态为启用的探索专题列表，按排序号排列，用于小程序探索页面展示。")
     @GetMapping("/active")
     public Result<List<TopicVO>> listActiveTopics() {
         return Result.success(topicService.listActiveTopics());

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java
index 6e38f29..d41fb78 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java
@@ -29,7 +29,7 @@ import java.util.*;
 import java.util.stream.Collectors;
 
 @Slf4j
-@Api(tags = "【内部接口】用户信息（Feign调用）")
+@Api(tags = "【内部接口】用户信息（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/user")
 @RequiredArgsConstructor
@@ -44,7 +44,8 @@ public class InternalUserController {
     private final WechatMiniAppClient wechatMiniAppClient;
     private final UserService userService;
 
-    @ApiOperation("Get admin basic info by ID")
+    @ApiOperation(value = "根据ID获取管理员基本信息", notes = "内部接口，供其他服务通过Feign查询管理员基础信息（ID、用户名、头像、企微姓名）。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/admin/info/{adminId}")
     public Result<AdminBasicDTO> getAdminInfo(@PathVariable Long adminId) {
         AdminUser admin = adminUserMapper.selectById(adminId);
@@ -55,7 +56,9 @@ public class InternalUserController {
         return Result.success(toBasicDTO(admin, wechatNameMap));
     }
 
-    @ApiOperation("Batch get admin basic info")
+    @ApiOperation(value = "批量获取管理员基本信息", notes = "内部接口，批量查询多个管理员的基础信息。"
+            + "传入adminId列表，返回对应的管理员信息列表。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/admin/batch-info")
     public Result<List<AdminBasicDTO>> batchGetAdminInfo(@RequestBody List<Long> adminIds) {
         if (adminIds == null || adminIds.isEmpty()) {
@@ -69,7 +72,9 @@ public class InternalUserController {
         return Result.success(result);
     }
 
-    @ApiOperation("Get all departments")
+    @ApiOperation(value = "获取所有部门列表", notes = "内部接口，获取企业微信同步的所有部门数据。"
+            + "用于通知规则配置等场景中的部门选择。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/departments")
     public Result<List<DepartmentDTO>> getDepartments() {
         List<WechatDepartment> depts = wechatDepartmentMapper.selectList(null);
@@ -85,7 +90,10 @@ public class InternalUserController {
         return Result.success(result);
     }
 
-    @ApiOperation("Get admin IDs belonging to a department")
+    @ApiOperation(value = "获取部门下的管理员ID列表", notes = "内部接口，查询指定部门下所有活跃管理员的ID。"
+            + "通过企微用户的部门归属关联到管理员账号。"
+            + "用于通知规则引擎按部门发送通知。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/admin/dept-members/{deptId}")
     public Result<List<Long>> getDeptAdminIds(@PathVariable Long deptId) {
         // Find wechat users in this department using FIND_IN_SET for exact match
@@ -113,7 +121,9 @@ public class InternalUserController {
         return Result.success(adminIds);
     }
 
-    @ApiOperation("Get admins by role key")
+    @ApiOperation(value = "根据角色标识获取管理员列表", notes = "内部接口，根据角色标识（如CUSTOMIZER、FINANCE等）查询该角色下所有活跃管理员。"
+            + "用于通知规则引擎按角色发送通知。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/admin/by-role-key")
     public Result<List<AdminBasicDTO>> getAdminsByRoleKey(@RequestParam String roleKey) {
         if (roleKey == null || roleKey.isBlank()) {
@@ -148,7 +158,10 @@ public class InternalUserController {
         return Result.success(result);
     }
 
-    @ApiOperation("Find C-end user ID by phone number")
+    @ApiOperation(value = "根据手机号查找C端用户ID", notes = "内部接口，根据手机号查找活跃的小程序用户。"
+            + "用于订单绑定流程中通过联系人手机号匹配用户。"
+            + "找不到时返回null（不报错）。"
+            + "不经过Gateway，仅服务间调用。")
     @GetMapping("/find-by-phone")
     public Result<Long> findUserByPhone(@RequestParam String phone) {
         if (phone == null || phone.isBlank()) {
@@ -162,7 +175,9 @@ public class InternalUserController {
         return Result.success(user != null ? user.getUserId() : null);
     }
 
-    @ApiOperation("Generate mini program URL Link for sharing")
+    @ApiOperation(value = "生成小程序URL Link", notes = "内部接口，生成小程序短链接用于分享。"
+            + "通过微信API生成URL Link，可在浏览器/短信中打开小程序指定页面。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/wechat/miniapp/generate-url-link")
     public Result<Map<String, Object>> generateUrlLink(
             @RequestParam String path, @RequestParam String query) {
@@ -170,7 +185,10 @@ public class InternalUserController {
         return Result.success(result);
     }
 
-    @ApiOperation("Send WeChat message to users")
+    @ApiOperation(value = "发送企业微信消息", notes = "内部接口，向指定的企微用户发送文本消息。"
+            + "toUserIds为企微用户ID列表，支持一次发送给多人。"
+            + "用于审批通知、订单提醒等场景。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/wechat/send-message")
     public Result<Void> sendWechatMessage(@RequestBody WechatMessageDTO dto) {
         if (dto.getToUserIds() == null || dto.getToUserIds().isEmpty()) {

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java
index e0d5a6d..d192b76 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWechatController.java
@@ -18,7 +18,7 @@ import org.springframework.web.bind.annotation.*;
  * No JWT auth required (excluded from TokenInterceptor via /internal/** pattern).
  */
 @Slf4j
-@Api(tags = "【内部接口】企微同步（Feign调用）")
+@Api(tags = "【内部接口】企微同步（Feign调用）", hidden = true)
 @RestController
 @RequestMapping("/internal/wechat")
 @RequiredArgsConstructor
@@ -27,9 +27,11 @@ public class InternalWechatController {
     private final WechatSyncService wechatSyncService;
     private final ExternalContactNotifyService externalContactNotifyService;
 
-    @ApiOperation("Sync single user from callback")
+    @ApiOperation(value = "同步单个企微用户（回调触发）", notes = "内部接口，由hl-callback-service在收到企微通讯录变更回调时调用。"
+            + "将单个用户的信息同步到本地wechat_user表。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/user/sync")
-    public Result<?> syncUser(@RequestBody WechatUserSyncDTO dto) {
+    public Result<Void> syncUser(@RequestBody WechatUserSyncDTO dto) {
         log.info("Internal: sync user userid={}", dto.getUserid());
         try {
             wechatSyncService.syncSingleUserFromDto(dto);
@@ -40,9 +42,11 @@ public class InternalWechatController {
         }
     }
 
-    @ApiOperation("Delete single user from callback")
+    @ApiOperation(value = "删除单个企微用户（回调触发）", notes = "内部接口，由hl-callback-service在收到企微成员离职回调时调用。"
+            + "从本地wechat_user表中删除该用户记录。"
+            + "不经过Gateway，仅服务间调用。")
     @DeleteMapping("/user/{userid}")
-    public Result<?> deleteUser(@PathVariable("userid") String userid) {
+    public Result<Void> deleteUser(@PathVariable("userid") String userid) {
         log.info("Internal: delete user userid={}", userid);
         try {
             wechatSyncService.deleteSingleUser(userid);
@@ -53,9 +57,11 @@ public class InternalWechatController {
         }
     }
 
-    @ApiOperation("Sync single department from callback")
+    @ApiOperation(value = "同步单个企微部门（回调触发）", notes = "内部接口，由hl-callback-service在收到企微部门变更回调时调用。"
+            + "将单个部门的信息同步到本地wechat_department表。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/department/sync")
-    public Result<?> syncDepartment(@RequestBody WechatDeptSyncDTO dto) {
+    public Result<Void> syncDepartment(@RequestBody WechatDeptSyncDTO dto) {
         log.info("Internal: sync department deptId={}", dto.getId());
         try {
             wechatSyncService.syncSingleDepartmentFromDto(dto);
@@ -66,18 +72,22 @@ public class InternalWechatController {
         }
     }
 
-    @ApiOperation("Receive external contact change event")
+    @ApiOperation(value = "接收外部联系人变更事件", notes = "内部接口，由hl-callback-service在收到企微外部联系人变更回调时调用。"
+            + "处理客户添加/删除等事件，异步执行通知逻辑。"
+            + "不经过Gateway，仅服务间调用。")
     @PostMapping("/external-contact/event")
-    public Result<?> handleExternalContactEvent(@RequestBody ExternalContactEventDTO dto) {
+    public Result<Void> handleExternalContactEvent(@RequestBody ExternalContactEventDTO dto) {
         log.info("Internal: external contact event changeType={}, userId={}, externalUserId={}",
                 dto.getChangeType(), dto.getUserId(), dto.getExternalUserId());
         externalContactNotifyService.processEventAsync(dto);
         return Result.success();
     }
 
-    @ApiOperation("Delete single department from callback")
+    @ApiOperation(value = "删除单个企微部门（回调触发）", notes = "内部接口，由hl-callback-service在收到企微部门删除回调时调用。"
+            + "从本地wechat_department表中删除该部门记录。"
+            + "不经过Gateway，仅服务间调用。")
     @DeleteMapping("/department/{deptId}")
-    public Result<?> deleteDepartment(@PathVariable("deptId") Long deptId) {
+    public Result<Void> deleteDepartment(@PathVariable("deptId") Long deptId) {
         log.info("Internal: delete department deptId={}", deptId);
         try {
             wechatSyncService.deleteSingleDepartment(deptId);

`hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java
index 44641ef..e3cf403 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/InternalWishController.java
@@ -15,7 +15,7 @@ import java.util.Map;
  * 祈愿内部接口（仅供 hl-mp-service BFF 通过 Feign 调用）
  * 不经过认证拦截器（/internal/** 已排除）
  */
-@Api(tags = "小程序接口")
+@Api(tags = "小程序接口", hidden = true)
 @RestController
 @RequestMapping("/internal/mp/wish")
 @RequiredArgsConstructor
@@ -23,13 +23,17 @@ public class InternalWishController {
 
     private final WishService wishService;
 
-    @ApiOperation("获取用户祈愿列表")
+    @ApiOperation(value = "获取用户祈愿列表", notes = "内部接口，获取用户的祈愿列表。"
+            + "\n\n**关联字典**：\n"
+            + "- wish_type（心愿类型）：返回字段wishType（1=想去的地方, 2=想做的事, 3=其他）")
     @GetMapping
     public Result<List<WishVO>> listWishes(@RequestParam Long userId) {
         return Result.success(wishService.listWishes(userId));
     }
 
-    @ApiOperation("创建祈愿")
+    @ApiOperation(value = "创建祈愿", notes = "内部接口，创建用户祈愿。"
+            + "\n\n**关联字典**：\n"
+            + "- wish_type（心愿类型）：请求参数wishType（1=想去的地方, 2=想做的事, 3=其他）")
     @PostMapping
     public Result<WishVO> createWish(@RequestParam Long userId,
                                      @RequestBody Map<String, Object> request) {

`hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java
index 5acc247..753577c 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/OfficialAccountCallbackController.java
@@ -24,7 +24,7 @@ import java.util.Map;
 @RestController
 @RequestMapping("/oa/callback")
 @RequiredArgsConstructor
-@Api(tags = "【回调接口】公众号回调")
+@Api(tags = "【回调接口】公众号回调", hidden = true)
 public class OfficialAccountCallbackController {
 
     private final WechatOfficialAccountClient oaClient;

`hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java
index 6d1ec31..38f0ad6 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/PublicDictController.java
@@ -24,7 +24,12 @@ public class PublicDictController {
 
     private final SysDictService sysDictService;
 
-    @ApiOperation("获取所有字典数据")
+    @ApiOperation(value = "获取所有字典数据（公开接口）", notes = "获取系统全部字典类型及其字典数据，供小程序C端使用。"
+            + "无需认证即可调用。返回格式与管理端 /admin/dict/all 一致。"
+            + "\n\n**字典层级说明**：\n"
+            + "- 每个元素包含 dictType（编码）、dictName（名称）、dataList（字典数据列表）\n"
+            + "- 前端通过 dictType 匹配业务字段，用 dataList 中的 dictValue/dictLabel 做翻译展示\n"
+            + "- 常用字典：order_status、product_status、id_card_type、gender、traveler_type、favorite_resource_type、footprint_resource_type\n")
     @GetMapping("/all")
     public Result<List<DictVO>> getAllDict() {
         return Result.success(sysDictService.getAllDictForPublic());

`hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java
index 5be6ee7..260eadd 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/SysDictController.java
@@ -26,7 +26,14 @@ public class SysDictController {
 
     // ======================== All Dict ========================
 
-    @ApiOperation("获取所有字典数据")
+    @ApiOperation(value = "获取所有字典数据", notes = "获取系统全部字典类型及其字典数据，按字典类型分组返回。"
+            + "用于后台管理系统初始化时一次性加载所有下拉选项。"
+            + "返回结果包含dictType编码、dictName名称、dataList数据列表。"
+            + "需要管理员认证。"
+            + "\n\n**字典层级说明**：\n"
+            + "- 字典类型（SysDictType）：一级分类，如 admin_status、order_status、id_card_type 等\n"
+            + "- 字典数据（SysDictData）：二级选项，归属于某个字典类型，如 admin_status 下的 ACTIVE/LOCKED/DISABLED\n"
+            + "- 前端通过 dictType 编码查找对应的 dataList，用 dictValue 匹配实际数据进行翻译展示\n")
     @GetMapping("/all")
     public Result<List<com.hulalv.user.vo.DictVO>> getAllDict() {
         return Result.success(sysDictService.getAllDictForPublic());
@@ -34,14 +41,21 @@ public class SysDictController {
 
     // ======================== Dict Type ========================
 
-    @ApiOperation("创建字典类型")
+    @ApiOperation(value = "创建字典类型", notes = "新建一个字典类型（如：订单状态、证件类型等）。"
+            + "字典类型编码（dictType）全局唯一，创建后不可修改。"
+            + "需要管理员认证，建议仅SUPER_ADMIN/ADMIN角色操作。"
+            + "\n\n**已有字典类型示例**：\n"
+            + "- admin_status（管理员状态）、common_status（通用状态）、login_status（登录状态）\n"
+            + "- order_status（订单状态）、product_status（产品状态）、rating_level（评价等级）\n"
+            + "- id_card_type（证件类型）、gender（性别）、traveler_type（出行人类型）\n"
+            + "- contact_channel_type（联系方式渠道类型）、favorite_resource_type（收藏资源类型）、footprint_resource_type（足迹资源类型）\n")
     @OperationLog(value = "创建字典类型", module = "字典管理")
     @PostMapping("/type")
     public Result<SysDictType> createDictType(@ApiParam("创建字典类型请求") @Valid @RequestBody CreateDictTypeRequest request) {
         return Result.success(sysDictService.createDictType(request));
     }
 
-    @ApiOperation("更新字典类型")
+    @ApiOperation(value = "更新字典类型", notes = "更新字典类型的名称、分类、备注等信息。字典类型编码（dictType）不可修改。")
     @OperationLog(value = "更新字典类型", module = "字典管理")
     @PutMapping("/type/{id}")
     public Result<SysDictType> updateDictType(@ApiParam("字典类型ID") @PathVariable Long id,
@@ -49,7 +63,9 @@ public class SysDictController {
         return Result.success(sysDictService.updateDictType(id, request));
     }
 
-    @ApiOperation("删除字典类型")
+    @ApiOperation(value = "删除字典类型", notes = "删除字典类型及其下所有字典数据（软删除）。"
+            + "如果该字典类型已被业务引用，删除后不影响已有数据，但新的表单将无法选择该字典值。"
+            + "需要管理员认证。")
     @OperationLog(value = "删除字典类型", module = "字典管理")
     @DeleteMapping("/type/{id}")
     public Result<Void> deleteDictType(@ApiParam("字典类型ID") @PathVariable Long id) {
@@ -57,7 +73,8 @@ public class SysDictController {
         return Result.success();
     }
 
-    @ApiOperation("分页查询字典类型")
+    @ApiOperation(value = "分页查询字典类型", notes = "分页查询字典类型列表，支持按分类（category）筛选。"
+            + "字典类型是字典数据的上级分组，管理字典类型即管理有哪些可供前端使用的下拉选项组。")
     @GetMapping("/type")
     public Result<PageResult<SysDictType>> listDictTypes(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -66,7 +83,7 @@ public class SysDictController {
         return Result.success(sysDictService.listDictTypes(page, pageSize, category));
     }
 
-    @ApiOperation("根据ID获取字典类型详情")
+    @ApiOperation(value = "根据ID获取字典类型详情", notes = "获取单个字典类型的详细信息，包括编码、名称、分类、状态等。")
     @GetMapping("/type/{dictTypeId}")
     public Result<SysDictType> getDictTypeById(@ApiParam("字典类型ID") @PathVariable Long dictTypeId) {
         return Result.success(sysDictService.getDictTypeById(dictTypeId));
@@ -74,14 +91,16 @@ public class SysDictController {
 
     // ======================== Dict Data ========================
 
-    @ApiOperation("创建字典数据")
+    @ApiOperation(value = "创建字典数据", notes = "在指定字典类型下新增一条字典数据项。"
+            + "dictValue为前端匹配的值（如ACTIVE），dictLabel为前端展示的标签（如'启用'）。"
+            + "支持树形字典数据（通过parentId设置父级）。")
     @OperationLog(value = "创建字典数据", module = "字典管理")
     @PostMapping("/data")
     public Result<SysDictData> createDictData(@ApiParam("创建字典数据请求") @Valid @RequestBody CreateDictDataRequest request) {
         return Result.success(sysDictService.createDictData(request));
     }
 
-    @ApiOperation("更新字典数据")
+    @ApiOperation(value = "更新字典数据", notes = "更新字典数据项的标签、样式类型、排序号等。dictValue建议不修改以免影响已有业务数据。")
     @OperationLog(value = "更新字典数据", module = "字典管理")
     @PutMapping("/data/{id}")
     public Result<SysDictData> updateDictData(@ApiParam("字典数据ID") @PathVariable Long id,
@@ -89,7 +108,7 @@ public class SysDictController {
         return Result.success(sysDictService.updateDictData(id, request));
     }
 
-    @ApiOperation("删除字典数据")
+    @ApiOperation(value = "删除字典数据", notes = "删除指定字典数据项（软删除）。删除后不影响已引用该字典值的业务数据。")
     @OperationLog(value = "删除字典数据", module = "字典管理")
     @DeleteMapping("/data/{id}")
     public Result<Void> deleteDictData(@ApiParam("字典数据ID") @PathVariable Long id) {
@@ -97,19 +116,23 @@ public class SysDictController {
         return Result.success();
     }
 
-    @ApiOperation("根据ID获取字典数据详情")
+    @ApiOperation(value = "根据ID获取字典数据详情", notes = "获取单个字典数据项的详细信息，包括dictValue、dictLabel、cssClass等。")
     @GetMapping("/data/detail/{dictDataId}")
     public Result<SysDictData> getDictDataById(@ApiParam("字典数据ID") @PathVariable Long dictDataId) {
         return Result.success(sysDictService.getDictDataById(dictDataId));
     }
 
-    @ApiOperation("按类型查询字典数据（树形结构）")
+    @ApiOperation(value = "按类型查询字典数据（树形结构）", notes = "根据字典类型ID查询其下所有字典数据，以树形结构返回（支持父子级字典数据）。"
+            + "用于多级联动下拉框场景（如省市区）。"
+            + "需要管理员认证。")
     @GetMapping("/data/tree/{dictTypeId}")
     public Result<List<SysDictData>> getDictDataTree(@ApiParam("字典类型ID") @PathVariable Long dictTypeId) {
         return Result.success(sysDictService.getDictDataTree(dictTypeId));
     }
 
-    @ApiOperation("按类型查询字典数据")
+    @ApiOperation(value = "按类型查询字典数据", notes = "根据字典类型编码（如order_status）查询其下所有字典数据（平铺列表）。"
+            + "用于单层下拉框场景。"
+            + "需要管理员认证。")
     @GetMapping("/data/{dictType}")
     public Result<List<SysDictData>> getDictDataByType(@ApiParam("字典类型编码") @PathVariable String dictType) {
         return Result.success(sysDictService.getDictDataByType(dictType));

`hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java
index 22b99cb..d58905e 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java
@@ -5,9 +5,9 @@ import com.hulalv.common.result.PageResult;
 import com.hulalv.common.result.Result;
 import com.hulalv.user.dto.CreateJobRequest;
 import com.hulalv.user.dto.UpdateJobRequest;
-import com.hulalv.user.entity.SysJob;
-import com.hulalv.user.entity.SysJobLog;
 import com.hulalv.user.service.SysJobService;
+import com.hulalv.user.vo.SysJobLogVO;
+import com.hulalv.user.vo.SysJobVO;
 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiOperation;
 import io.swagger.annotations.ApiParam;
@@ -24,22 +24,39 @@ public class SysJobController {
 
     private final SysJobService sysJobService;
 
-    @ApiOperation("创建定时任务")
+    @ApiOperation(value = "创建定时任务", notes = "创建新的定时任务。"
+            + "invokeTarget格式为'Bean名称.方法名'（如wechatSyncService.syncAll），方法必须是无参公开方法。"
+            + "cronExpression为标准6位Cron表达式（秒 分 时 日 月 周）。"
+            + "创建后任务默认为暂停状态（PAUSED），需手动调用[恢复任务]接口启用。"
+            + "\n\n**关联字典**：\n"
+            + "- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步\n"
+            + "- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发\n"
+            + "- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停\n\n"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "创建定时任务", module = "定时任务")
     @PostMapping
-    public Result<SysJob> createJob(@ApiParam("创建定时任务请求") @Valid @RequestBody CreateJobRequest request) {
+    public Result<SysJobVO> createJob(@ApiParam("创建定时任务请求") @Valid @RequestBody CreateJobRequest request) {
         return Result.success(sysJobService.createJob(request));
     }
 
-    @ApiOperation("更新定时任务")
+    @ApiOperation(value = "更新定时任务",
+            notes = "更新指定定时任务的名称、Cron表达式、调用目标等信息。\n"
+                + "修改Cron表达式后任务将按新的计划执行。\n\n"
+                + "**关联字典**：\n"
+                + "- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步\n"
+                + "- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发\n\n"
+                + "**权限**：需要SUPER_ADMIN角色。")
     @OperationLog(value = "更新定时任务", module = "定时任务")
     @PutMapping("/{jobId}")
-    public Result<SysJob> updateJob(@ApiParam("定时任务ID") @PathVariable Long jobId,
+    public Result<SysJobVO> updateJob(@ApiParam("定时任务ID") @PathVariable Long jobId,
                                      @ApiParam("更新定时任务请求") @Valid @RequestBody UpdateJobRequest request) {
         return Result.success(sysJobService.updateJob(jobId, request));
     }
 
-    @ApiOperation("删除定时任务")
+    @ApiOperation(value = "删除定时任务",
+            notes = "删除指定的定时任务（软删除），同时从调度器中移除该任务。\n\n"
+                + "**权限**：需要SUPER_ADMIN角色。\n"
+                + "**注意**：删除后任务将不再执行，但历史执行日志仍可查看。")
     @OperationLog(value = "删除定时任务", module = "定时任务")
     @DeleteMapping("/{jobId}")
     public Result<Void> deleteJob(@ApiParam("定时任务ID") @PathVariable Long jobId) {
@@ -47,15 +64,22 @@ public class SysJobController {
         return Result.success();
     }
 
-    @ApiOperation("分页查询定时任务")
+    @ApiOperation(value = "分页查询定时任务", notes = "分页查询定时任务列表。"
+            + "\n\n**关联字典**：\n"
+            + "- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步\n"
+            + "- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发\n"
+            + "- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停")
     @GetMapping
-    public Result<PageResult<SysJob>> listJobs(
+    public Result<PageResult<SysJobVO>> listJobs(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
             @ApiParam("每页条数") @RequestParam(defaultValue = "20") int pageSize) {
         return Result.success(sysJobService.listJobs(page, pageSize));
     }
 
-    @ApiOperation("暂停任务")
+    @ApiOperation(value = "暂停任务", notes = "暂停指定的定时任务，任务状态变为PAUSED。"
+            + "暂停后任务不再按Cron计划执行，但可通过[恢复任务]接口重新启用。"
+            + "\n\n**关联字典**：job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停\n\n"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "暂停任务", module = "定时任务")
     @PostMapping("/{jobId}/pause")
     public Result<Void> pauseJob(@ApiParam("定时任务ID") @PathVariable Long jobId) {
@@ -63,7 +87,10 @@ public class SysJobController {
         return Result.success();
     }
 
-    @ApiOperation("恢复任务")
+    @ApiOperation(value = "恢复任务", notes = "恢复已暂停的定时任务，任务状态变为ACTIVE。"
+            + "恢复后任务按Cron计划继续执行。"
+            + "\n\n**关联字典**：job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停\n\n"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "恢复任务", module = "定时任务")
     @PostMapping("/{jobId}/resume")
     public Result<Void> resumeJob(@ApiParam("定时任务ID") @PathVariable Long jobId) {
@@ -71,7 +98,10 @@ public class SysJobController {
         return Result.success();
     }
 
-    @ApiOperation("立即执行一次")
+    @ApiOperation(value = "立即执行一次", notes = "立即触发一次定时任务的执行，不影响原有的Cron计划。"
+            + "无论任务当前状态是ACTIVE还是PAUSED，都可以手动触发。"
+            + "执行结果可在任务日志中查看。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "立即执行任务", module = "定时任务")
     @PostMapping("/{jobId}/trigger")
     public Result<Void> triggerJob(@ApiParam("定时任务ID") @PathVariable Long jobId) {
@@ -79,9 +109,12 @@ public class SysJobController {
         return Result.success();
     }
 
-    @ApiOperation("查询任务日志")
+    @ApiOperation(value = "查询任务日志", notes = "分页查询指定定时任务的执行日志，按执行时间倒序排列。"
+            + "日志包含执行状态（成功/失败）、执行耗时、异常信息等。"
+            + "\n\n**关联字典**：job_log_status（日志状态）：SUCCESS=成功, FAIL=失败\n\n"
+            + "需要管理员认证。")
     @GetMapping("/{jobId}/logs")
-    public Result<PageResult<SysJobLog>> listJobLogs(
+    public Result<PageResult<SysJobLogVO>> listJobLogs(
             @ApiParam("定时任务ID") @PathVariable Long jobId,
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
             @ApiParam("每页条数") @RequestParam(defaultValue = "20") int pageSize) {

`hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java
index 46e8615..44e4293 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/SysMenuController.java
@@ -24,14 +24,27 @@ public class SysMenuController {
 
     private final SysMenuService sysMenuService;
 
-    @ApiOperation("创建菜单")
+    @ApiOperation(value = "创建菜单", notes = "创建新的菜单/目录/按钮。"
+            + "menuType取值：DIRECTORY=目录（含子菜单） MENU=页面菜单 BUTTON=操作按钮。"
+            + "目录和菜单需设置path路由路径，菜单还需设置component组件路径。"
+            + "按钮类型需设置permissionCode权限标识（如system:user:add）。"
+            + "需要SUPER_ADMIN角色。"
+            + "\n\n**关联字典**：\n"
+            + "- menu_type（菜单类型）：请求/返回字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮）\n"
+            + "- common_status（通用状态）：返回字段status")
     @OperationLog(value = "创建菜单", module = "菜单管理")
     @PostMapping
     public Result<SysMenu> createMenu(@ApiParam("创建菜单请求") @Valid @RequestBody CreateMenuRequest request) {
         return Result.success(sysMenuService.createMenu(request));
     }
 
-    @ApiOperation("更新菜单")
+    @ApiOperation(value = "更新菜单",
+            notes = "更新指定菜单的名称、路径、组件、图标、排序、状态等信息。\n\n"
+                + "**权限**：需要SUPER_ADMIN角色。\n"
+                + "**注意**：修改后需清除 Redis 菜单缓存才能生效。\n\n"
+                + "**关联字典**：\n"
+                + "- menu_type（菜单类型）：请求字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮）\n"
+                + "- common_status（通用状态）：请求字段status")
     @OperationLog(value = "更新菜单", module = "菜单管理")
     @PutMapping("/{menuId}")
     public Result<SysMenu> updateMenu(@ApiParam("菜单ID") @PathVariable Long menuId,
@@ -39,7 +52,11 @@ public class SysMenuController {
         return Result.success(sysMenuService.updateMenu(menuId, request));
     }
 
-    @ApiOperation("删除菜单")
+    @ApiOperation(value = "删除菜单",
+            notes = "删除指定的菜单/目录/按钮（软删除）。\n\n"
+                + "**权限**：需要SUPER_ADMIN角色。\n"
+                + "**注意**：如果该菜单有子菜单，需先删除子菜单才能删除父菜单。"
+                + "删除后需清除 Redis 菜单缓存才能生效。")
     @OperationLog(value = "删除菜单", module = "菜单管理")
     @DeleteMapping("/{menuId}")
     public Result<Void> deleteMenu(@ApiParam("菜单ID") @PathVariable Long menuId) {
@@ -47,25 +64,42 @@ public class SysMenuController {
         return Result.success();
     }
 
-    @ApiOperation("获取菜单详情")
+    @ApiOperation(value = "获取菜单详情",
+            notes = "获取指定菜单的详细信息，包括名称、路径、组件、图标、排序、权限标识等。\n\n"
+                + "**权限**：需要管理员登录。\n\n"
+                + "**关联字典**：\n"
+                + "- menu_type（菜单类型）：返回字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮）\n"
+                + "- common_status（通用状态）：返回字段status")
     @GetMapping("/{menuId}")
     public Result<SysMenu> getMenu(@ApiParam("菜单ID") @PathVariable Long menuId) {
         return Result.success(sysMenuService.getMenuById(menuId));
     }
 
-    @ApiOperation("获取完整菜单树")
+    @ApiOperation(value = "获取完整菜单树", notes = "获取系统所有菜单的完整树形结构。"
+            + "用于角色权限配置页面展示完整的菜单树供勾选。"
+            + "仅SUPER_ADMIN可查看完整菜单树。"
+            + "需要管理员认证。"
+            + "\n\n**关联字典**：\n"
+            + "- menu_type（菜单类型）：返回字段menuType\n"
+            + "- common_status（通用状态）：返回字段status")
     @GetMapping("/tree")
     public Result<List<SysMenu>> getMenuTree() {
         return Result.success(sysMenuService.getMenuTree());
     }
 
-    @ApiOperation("获取角色菜单树")
+    @ApiOperation(value = "获取角色菜单树",
+            notes = "获取指定角色已分配的菜单树形结构。\n"
+                + "用于角色权限配置页面，展示该角色已拥有的菜单权限。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/tree/role/{roleId}")
     public Result<List<SysMenu>> getMenuTreeByRoleId(@ApiParam("角色ID") @PathVariable Long roleId) {
         return Result.success(sysMenuService.getMenuTreeByRoleId(roleId));
     }
 
-    @ApiOperation("获取当前管理员菜单")
+    @ApiOperation(value = "获取当前管理员菜单", notes = "获取当前登录管理员的菜单树（基于其当前角色的权限）。"
+            + "SUPER_ADMIN角色返回完整菜单树，其他角色返回已授权的菜单子集。"
+            + "前端登录后调用此接口动态生成路由和侧边栏菜单。"
+            + "需要管理员认证。")
     @GetMapping("/my")
     public Result<List<SysMenu>> getMyMenus(HttpServletRequest request) {
         Long adminId = (Long) request.getAttribute("adminId");

`hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java
index 1e4979d..52f6507 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/SysRoleController.java
@@ -25,14 +25,19 @@ public class SysRoleController {
 
     private final SysRoleService sysRoleService;
 
-    @ApiOperation("创建角色")
+    @ApiOperation(value = "创建角色", notes = "创建新的系统角色。"
+            + "角色标识（roleKey）全局唯一，创建后不可修改，用于代码中的权限判断。"
+            + "创建后需通过[分配菜单权限]接口为角色授权菜单。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "创建角色", module = "角色管理")
     @PostMapping
     public Result<SysRole> createRole(@ApiParam("创建角色请求") @Valid @RequestBody CreateRoleRequest request) {
         return Result.success(sysRoleService.createRole(request));
     }
 
-    @ApiOperation("更新角色")
+    @ApiOperation(value = "更新角色", notes = "更新角色名称、状态等信息。角色标识（roleKey）不可修改。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：ACTIVE=启用, DISABLED=禁用\n")
     @OperationLog(value = "更新角色", module = "角色管理")
     @PutMapping("/{roleId}")
     public Result<SysRole> updateRole(@ApiParam("角色ID") @PathVariable Long roleId,
@@ -40,7 +45,10 @@ public class SysRoleController {
         return Result.success(sysRoleService.updateRole(roleId, request));
     }
 
-    @ApiOperation("删除角色")
+    @ApiOperation(value = "删除角色", notes = "删除指定角色（软删除）。"
+            + "如果该角色下还有关联的管理员，将无法删除，需先解除绑定关系。"
+            + "内置角色（SUPER_ADMIN等）不可删除。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "删除角色", module = "角色管理")
     @DeleteMapping("/{roleId}")
     public Result<Void> deleteRole(@ApiParam("角色ID") @PathVariable Long roleId) {
@@ -48,13 +56,17 @@ public class SysRoleController {
         return Result.success();
     }
 
-    @ApiOperation("获取角色详情(含菜单ID)")
+    @ApiOperation(value = "获取角色详情(含菜单ID)", notes = "获取角色基本信息及其已分配的菜单ID列表。"
+            + "返回role对象和menuIds数组，用于角色编辑页面回显已勾选的菜单。"
+            + "需要管理员认证。")
     @GetMapping("/{roleId}")
     public Result<java.util.Map<String, Object>> getRoleDetail(@ApiParam("角色ID") @PathVariable Long roleId) {
         return Result.success(sysRoleService.getRoleDetail(roleId));
     }
 
-    @ApiOperation("分页查询角色")
+    @ApiOperation(value = "分页查询角色", notes = "分页查询系统角色列表，支持按状态筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- common_status（通用状态）：ACTIVE=启用, DISABLED=禁用（筛选条件+列表展示）\n")
     @GetMapping
     public Result<PageResult<SysRole>> listRoles(
             @ApiParam("页码") @RequestParam(defaultValue = "1") int page,
@@ -63,13 +75,19 @@ public class SysRoleController {
         return Result.success(sysRoleService.listRoles(page, pageSize, status));
     }
 
-    @ApiOperation("获取所有角色(下拉)")
+    @ApiOperation(value = "获取所有角色(下拉)", notes = "获取所有状态正常的角色列表，用于下拉选择框。"
+            + "不分页，返回全部角色。创建管理员、筛选管理员列表时使用。"
+            + "需要管理员认证。")
     @GetMapping("/all")
     public Result<List<SysRole>> getAllRoles() {
         return Result.success(sysRoleService.getAllRoles());
     }
 
-    @ApiOperation("分配菜单权限")
+    @ApiOperation(value = "分配菜单权限", notes = "为指定角色分配菜单权限（全量覆盖模式）。"
+            + "传入的menuIds将完全替换该角色原有的菜单权限。"
+            + "分配后该角色的所有在线管理员下次请求 /admin/menu/my 时会获取到新的菜单树。"
+            + "注意：需同步清除Redis中的菜单缓存，否则前端拿到的是旧菜单。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "分配菜单权限", module = "角色管理")
     @PutMapping("/{roleId}/menus")
     public Result<Void> assignMenus(@ApiParam("角色ID") @PathVariable Long roleId,

`hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java
index 5f71654..ac3f257 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/TravelerController.java
@@ -22,7 +22,15 @@ public class TravelerController {
 
     private final TravelerService travelerService;
 
-    @ApiOperation("新增出行人")
+    @ApiOperation(value = "新增出行人", notes = "为当前用户添加一位出行人信息，用于下单时选择。"
+            + "出行人类型（成人/儿童/婴儿）根据出生日期自动判断，无需手动传入。"
+            + "如果传入身份证号，后端自动校验格式并解析性别。"
+            + "每个用户最多可添加20位出行人。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- gender（性别）：请求/返回字段gender（0=女, 1=男）\n"
+            + "- id_card_type（证件类型）：请求/返回字段idCardType（ID_CARD=身份证, PASSPORT=护照等）\n"
+            + "- traveler_type（出行人类型）：返回字段travelerType（ADULT=成人, CHILD=儿童, INFANT=婴儿，自动计算）")
     @PostMapping
     public Result<Traveler> addTraveler(HttpServletRequest request,
                                           @ApiParam("出行人信息") @Valid @RequestBody TravelerRequest travelerRequest) {
@@ -31,7 +39,14 @@ public class TravelerController {
         return Result.success(traveler);
     }
 
-    @ApiOperation("出行人列表")
+    @ApiOperation(value = "出行人列表", notes = "获取当前用户的所有出行人列表。"
+            + "如果用户已完成实名认证（realName不为空），列表首项会自动注入一个'本人'虚拟出行人（travelerId=0）。"
+            + "默认出行人排在前面，其余按创建时间排序。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- gender（性别）：返回字段gender\n"
+            + "- id_card_type（证件类型）：返回字段idCardType\n"
+            + "- traveler_type（出行人类型）：返回字段travelerType")
     @GetMapping
     public Result<List<Traveler>> listTravelers(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
@@ -39,7 +54,11 @@ public class TravelerController {
         return Result.success(travelers);
     }
 
-    @ApiOperation("出行人详情")
+    @ApiOperation(value = "出行人详情", notes = "获取指定出行人的详细信息。"
+            + "\n\n**关联字典**：\n"
+            + "- gender（性别）：返回字段gender\n"
+            + "- id_card_type（证件类型）：返回字段idCardType\n"
+            + "- traveler_type（出行人类型）：返回字段travelerType")
     @GetMapping("/{travelerId}")
     public Result<Traveler> getTraveler(HttpServletRequest request,
                                           @ApiParam("出行人ID") @PathVariable Long travelerId) {
@@ -48,7 +67,11 @@ public class TravelerController {
         return Result.success(traveler);
     }
 
-    @ApiOperation("更新出行人")
+    @ApiOperation(value = "更新出行人", notes = "更新指定出行人的信息。"
+            + "\n\n**关联字典**：\n"
+            + "- gender（性别）：请求/返回字段gender\n"
+            + "- id_card_type（证件类型）：请求/返回字段idCardType\n"
+            + "- traveler_type（出行人类型）：返回字段travelerType（自动计算）")
     @PutMapping("/{travelerId}")
     public Result<Traveler> updateTraveler(HttpServletRequest request,
                                               @ApiParam("出行人ID") @PathVariable Long travelerId,
@@ -58,7 +81,10 @@ public class TravelerController {
         return Result.success(traveler);
     }
 
-    @ApiOperation("删除出行人")
+    @ApiOperation(value = "删除出行人",
+            notes = "删除指定的出行人记录（软删除）。\n\n"
+                + "**权限**：需要小程序用户认证。\n"
+                + "**注意**：如果该出行人已关联到未完成的订单，删除不影响订单中的出行人快照数据。")
     @DeleteMapping("/{travelerId}")
     public Result<Void> deleteTraveler(HttpServletRequest request,
                                           @ApiParam("出行人ID") @PathVariable Long travelerId) {
@@ -67,7 +93,10 @@ public class TravelerController {
         return Result.success();
     }
 
-    @ApiOperation("设为默认出行人")
+    @ApiOperation(value = "设为默认出行人", notes = "将指定出行人设为默认。"
+            + "每个用户只能有一个默认出行人，设置新的默认会自动取消原来的默认。"
+            + "默认出行人在下单时会被自动选中。"
+            + "需要小程序用户认证。")
     @PutMapping("/{travelerId}/default")
     public Result<Void> setDefault(HttpServletRequest request,
                                       @ApiParam("出行人ID") @PathVariable Long travelerId) {

`hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java
index f5d5dc0..24ecd04 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/UserController.java
@@ -29,28 +29,42 @@ public class UserController {
     private final SmsService smsService;
     private final FavoriteService favoriteService;
 
-    @ApiOperation("发送短信验证码")
+    @ApiOperation(value = "发送短信验证码", notes = "向指定手机号发送6位数字短信验证码，用于小程序手机号登录。"
+            + "同一手机号60秒内不可重复发送，每日最多发送10次。"
+            + "验证码有效期5分钟。"
+            + "无需认证即可调用。")
     @PostMapping("/sms/send")
     public Result<Void> sendSmsCode(@ApiParam("发送短信验证码请求") @Valid @RequestBody SendSmsRequest request) {
         smsService.sendVerificationCode(request.getPhone());
         return Result.success();
     }
 
-    @ApiOperation("手机号验证码登录")
+    @ApiOperation(value = "手机号验证码登录", notes = "小程序用户通过手机号+短信验证码登录。"
+            + "首次登录自动注册账号，返回JWT Token。"
+            + "登录成功后若needProfile=true，表示需要补充个人信息（实名认证），前端应跳转到信息补充页。"
+            + "无需认证即可调用。")
     @PostMapping("/login/sms")
     public Result<LoginResponse> loginBySms(@ApiParam("短信验证码登录请求") @Valid @RequestBody SmsLoginRequest request) {
         LoginResponse response = userService.loginBySms(request);
         return Result.success(response);
     }
 
-    @ApiOperation("微信登录")
+    @ApiOperation(value = "微信登录", notes = "小程序用户通过微信授权码（wx.login获取的code）登录。"
+            + "可选传入phoneCode用于获取手机号绑定，avatar和nickname用于设置头像昵称。"
+            + "首次登录自动注册，返回JWT Token。needProfile=true表示需补充实名信息。"
+            + "无需认证即可调用。")
     @PostMapping("/login")
     public Result<LoginResponse> login(@ApiParam("微信登录请求") @Valid @RequestBody LoginRequest request) {
         LoginResponse response = userService.login(request);
         return Result.success(response);
     }
 
-    @ApiOperation("获取用户信息")
+    @ApiOperation(value = "获取用户信息", notes = "获取当前登录用户的个人资料，包括昵称、头像、手机号（脱敏）、实名信息等。"
+            + "手机号返回脱敏格式（如138****0000），证件号同样脱敏处理。"
+            + "需要小程序用户认证（Token中的userId）。"
+            + "\n\n**关联字典**：\n"
+            + "- id_card_type（证件类型）：ID_CARD=身份证, PASSPORT=护照\n"
+            + "- gender（性别）：0=女, 1=男\n")
     @GetMapping("/profile")
     public Result<UserVO> getProfile(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
@@ -58,7 +72,14 @@ public class UserController {
         return Result.success(user);
     }
 
-    @ApiOperation("更新用户信息")
+    @ApiOperation(value = "更新用户信息", notes = "更新当前用户的个人资料。"
+            + "首次登录补充信息时realName/idCardType/idCardNo为必填（使用ProfileCompletion验证组）。"
+            + "如果传入身份证号，后端自动解析性别和出生日期。"
+            + "更新手机号后会自动绑定匹配的待绑定订单。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- id_card_type（证件类型）：ID_CARD=身份证, PASSPORT=护照（请求参数idCardType）\n"
+            + "- gender（性别）：0=女, 1=男\n")
     @PutMapping("/profile")
     public Result<UserVO> updateProfile(HttpServletRequest request,
                                        @ApiParam("更新用户信息请求") @Valid @RequestBody UpdateProfileRequest updateRequest) {
@@ -67,7 +88,8 @@ public class UserController {
         return Result.success(user);
     }
 
-    @ApiOperation("用户登出")
+    @ApiOperation(value = "用户登出", notes = "清除当前用户的登录状态并使Token失效。"
+            + "需要小程序用户认证。")
     @PostMapping("/logout")
     public Result<Void> logout(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
@@ -75,7 +97,10 @@ public class UserController {
         return Result.success();
     }
 
-    @ApiOperation("注销账号")
+    @ApiOperation(value = "注销账号", notes = "永久注销当前用户账号（软删除）。"
+            + "注销后该账号的openid和手机号将被释放，可用于重新注册。"
+            + "注销操作不可撤销，请谨慎调用。"
+            + "需要小程序用户认证。")
     @DeleteMapping("/account")
     public Result<Void> deleteAccount(HttpServletRequest request) {
         Long userId = (Long) request.getAttribute("userId");
@@ -83,7 +108,12 @@ public class UserController {
         return Result.success();
     }
 
-    @ApiOperation("检查是否已收藏")
+    @ApiOperation(value = "检查是否已收藏", notes = "检查当前用户是否已收藏指定类型的资源。"
+            + "返回true=已收藏，false=未收藏。"
+            + "targetType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT/EXPLORE等。"
+            + "需要小程序用户认证。"
+            + "\n\n**关联字典**：\n"
+            + "- favorite_resource_type（收藏资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索（请求参数targetType）\n")
     @GetMapping("/favorite/check")
     public Result<Boolean> checkFavorite(HttpServletRequest request,
                                           @ApiParam("目标类型") @RequestParam String targetType,

`hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java b/hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java
index 2b68e9c..03cca6a 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/controller/WechatSyncController.java
@@ -23,7 +23,10 @@ public class WechatSyncController {
 
     private final WechatSyncService wechatSyncService;
 
-    @ApiOperation("手动同步部门")
+    @ApiOperation(value = "手动同步部门", notes = "从企业微信拉取最新的部门列表并同步到本地数据库。"
+            + "通常在企业微信后台调整组织架构后手动触发。"
+            + "也可通过定时任务自动执行。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "手动同步部门", module = "企业微信同步")
     @PostMapping("/sync/departments")
     public Result<Void> syncDepartments() {
@@ -31,7 +34,10 @@ public class WechatSyncController {
         return Result.success();
     }
 
-    @ApiOperation("手动同步用户")
+    @ApiOperation(value = "手动同步用户", notes = "从企业微信拉取所有部门的成员列表并同步到本地数据库。"
+            + "包括姓名、手机号、职位、部门归属等信息。"
+            + "需先同步部门再同步用户，或直接使用[同步全部]接口。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "手动同步用户", module = "企业微信同步")
     @PostMapping("/sync/users")
     public Result<Void> syncUsers() {
@@ -39,7 +45,10 @@ public class WechatSyncController {
         return Result.success();
     }
 
-    @ApiOperation("手动同步全部（部门+用户）")
+    @ApiOperation(value = "手动同步全部（部门+用户）", notes = "一键同步企业微信的部门和用户数据，先同步部门再同步用户。"
+            + "推荐使用此接口而非单独同步，确保部门和用户数据一致性。"
+            + "同步过程为异步执行，接口立即返回成功。"
+            + "需要SUPER_ADMIN角色。")
     @OperationLog(value = "手动同步全部", module = "企业微信同步")
     @PostMapping("/sync/all")
     public Result<Void> syncAll() {
@@ -47,7 +56,13 @@ public class WechatSyncController {
         return Result.success();
     }
 
-    @ApiOperation("查询企业微信用户（分页+搜索）")
+    @ApiOperation(value = "查询企业微信用户（分页+搜索）", notes = "分页查询已同步的企业微信用户列表。"
+            + "支持按姓名/手机号/职位关键词搜索，按部门ID和状态筛选。"
+            + "status取值：1=已激活 2=已禁用 4=未关注。"
+            + "用于管理员绑定企微账号时选择企微用户。"
+            + "需要管理员认证。"
+            + "\n\n**关联字典**：\n"
+            + "- wechat_user_status（企微用户状态）：请求参数status和返回字段status（1=已激活, 2=已禁用, 4=未关注）")
     @GetMapping("/users")
     public Result<PageResult<WechatUser>> listWechatUsers(
             @ApiParam("页码") @RequestParam(defaultValue = "1") Integer page,
@@ -58,21 +73,29 @@ public class WechatSyncController {
         return Result.success(wechatSyncService.listWechatUsers(page, pageSize, keyword, deptId, status));
     }
 
-    @ApiOperation("部门列表（部门管理页面）")
+    @ApiOperation(value = "部门列表（部门管理页面）",
+            notes = "获取已同步的所有企业微信部门列表（平铺结构），用于部门管理页面展示。\n"
+                + "包含部门ID、名称、上级部门ID、排序等信息。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/departments")
     public Result<List<WechatDepartment>> listAllDepartments() {
         List<WechatDepartment> departments = wechatSyncService.listAllDepartments();
         return Result.success(departments);
     }
 
-    @ApiOperation("部门树（下拉筛选）")
+    @ApiOperation(value = "部门树（下拉筛选）", notes = "以树形结构返回企业微信部门数据。"
+            + "用于部门筛选下拉框，每个节点包含id/label/children。"
+            + "需要管理员认证。")
     @GetMapping("/departments/tree")
     public Result<List<Map<String, Object>>> listDepartmentsTree() {
         List<Map<String, Object>> tree = wechatSyncService.listDepartmentsTree();
         return Result.success(tree);
     }
 
-    @ApiOperation("同步状态（最后同步时间）")
+    @ApiOperation(value = "同步状态（最后同步时间）",
+            notes = "获取企业微信数据的最后同步时间和状态。\n"
+                + "返回部门和用户各自的最后同步时间，用于管理页面展示同步状态。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/sync/status")
     public Result<Map<String, Object>> getSyncStatus() {
         Map<String, Object> status = wechatSyncService.getSyncStatus();

`hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java
index 3dcbbb3..3bde0cd 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java
@@ -6,13 +6,15 @@ import lombok.Data;
 import javax.validation.constraints.NotBlank;
 
 @Data
-@ApiModel("管理员登录请求")
+@ApiModel(value = "管理员登录请求", description = "后台管理员通过用户名+密码登录，新设备首次登录需2FA验证")
 public class AdminLoginRequest {
-    @ApiModelProperty(value = "用户名", required = true, example = "admin")
+    @ApiModelProperty(value = "用户名", required = true, example = "admin",
+            notes = "管理员账号的用户名，由SUPER_ADMIN创建时指定")
     @NotBlank(message = "用户名不能为空")
     private String username;
 
-    @ApiModelProperty(value = "密码", required = true, example = "Admin@2026")
+    @ApiModelProperty(value = "密码", required = true, example = "Admin@2026",
+            notes = "须包含大小写字母和数字，长度8-128位。默认密码为Admin@123456")
     @NotBlank(message = "密码不能为空")
     private String password;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java
index 9c59721..160c8c7 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java
@@ -9,7 +9,7 @@ import javax.validation.constraints.NotBlank;
 @Data
 @ApiModel("联系我们请求")
 public class ContactRequest {
-    @ApiModelProperty(value = "渠道类型：ABOUT=关于我们 ONLINE_CS=在线客服 PHONE=电话咨询", required = true, example = "PHONE")
+    @ApiModelProperty(value = "渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询", required = true, example = "PHONE")
     @NotBlank(message = "渠道类型不能为空")
     private String channelType;
 
@@ -32,6 +32,6 @@ public class ContactRequest {
     @ApiModelProperty(value = "排序号（越小越靠前）", example = "1")
     private Integer sortOrder;
 
-    @ApiModelProperty(value = "状态：0=下线 1=上线", example = "1")
+    @ApiModelProperty(value = "状态，关联字典common_status：0=下线, 1=上线", example = "1")
     private Integer status;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java
index 5d0ffe3..72f20fd 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java
@@ -7,17 +7,20 @@ import javax.validation.constraints.NotBlank;
 import java.util.List;
 
 @Data
-@ApiModel("创建管理员请求")
+@ApiModel(value = "创建管理员请求", description = "创建后台管理员账号，默认密码Admin@123456")
 public class CreateAdminRequest {
-    @ApiModelProperty(value = "用户名", required = true, example = "zhangsan")
+    @ApiModelProperty(value = "用户名", required = true, example = "zhangsan",
+            notes = "全局唯一的登录用户名，创建后不可修改")
     @NotBlank(message = "用户名不能为空")
     private String username;
 
     /** 角色ID列表（多角色），兼容旧的单角色 roleId */
-    @ApiModelProperty(value = "角色ID列表（多角色）", example = "[1,2]")
+    @ApiModelProperty(value = "角色ID列表（多角色）", example = "[1,2]",
+            notes = "支持分配多个角色，管理员登录后可通过切换角色接口切换当前活跃角色")
     private List<Long> roleIds;
 
     /** @deprecated 兼容旧接口，优先使用 roleIds */
-    @ApiModelProperty(value = "角色ID（已废弃，请使用roleIds）", example = "1")
+    @ApiModelProperty(value = "角色ID（已废弃，请使用roleIds）", example = "1",
+            notes = "兼容旧接口的单角色参数，优先使用roleIds")
     private Long roleId;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java
index dff93b6..5d8d05b 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java
@@ -12,18 +12,18 @@ public class CreateJobRequest {
     @NotBlank(message = "任务名称不能为空")
     private String jobName;
 
-    @ApiModelProperty(value = "任务分组", example = "SYSTEM")
+    @ApiModelProperty(value = "任务分组，字典类型：job_group（DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步）", example = "SYSTEM")
     private String jobGroup;
 
-    @ApiModelProperty(value = "调用目标（Bean名称.方法名）", required = true, example = "wechatSyncService.syncDepartments")
+    @ApiModelProperty(value = "调用目标（Bean名称.方法名），方法必须是无参公开方法", required = true, example = "wechatSyncService.syncDepartments")
     @NotBlank(message = "调用目标不能为空")
     private String invokeTarget;
 
-    @ApiModelProperty(value = "Cron表达式", required = true, example = "0 0 2 * * ?")
+    @ApiModelProperty(value = "Cron表达式，标准6位（秒 分 时 日 月 周）", required = true, example = "0 0 2 * * ?")
     @NotBlank(message = "Cron表达式不能为空")
     private String cronExpression;
 
-    @ApiModelProperty(value = "计划执行策略：0=默认 1=立即触发 2=触发一次 3=不触发", example = "0")
+    @ApiModelProperty(value = "计划执行策略，字典类型：job_misfire_policy（DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发）", example = "DEFAULT")
     private String misfirePolicy;
 
     @ApiModelProperty(value = "是否允许并发执行", example = "false")

`hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java
index cbb0455..b7b4fbb 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/FavoriteRequest.java
@@ -7,13 +7,15 @@ import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.NotNull;
 
 @Data
-@ApiModel("收藏请求")
+@ApiModel(value = "收藏请求", description = "添加收藏时的请求体，指定收藏的资源类型和ID")
 public class FavoriteRequest {
-    @ApiModelProperty(value = "收藏类型", required = true, example = "SCENIC_SPOT")
+    @ApiModelProperty(value = "收藏类型，关联字典favorite_resource_type", required = true, example = "SCENIC_SPOT",
+            notes = "可选值：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索分类")
     @NotBlank(message = "目标类型不能为空")
     private String targetType;
 
-    @ApiModelProperty(value = "收藏目标ID", required = true, example = "1")
+    @ApiModelProperty(value = "收藏目标ID", required = true, example = "1",
+            notes = "对应资源的ID，如景区ID、活动ID等")
     @NotNull(message = "目标ID不能为空")
     private Long targetId;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java
index 6a9905c..a700a4d 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/FootprintRequest.java
@@ -7,13 +7,15 @@ import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.NotNull;
 
 @Data
-@ApiModel("足迹请求")
+@ApiModel(value = "足迹请求", description = "记录用户浏览足迹时的请求体")
 public class FootprintRequest {
-    @ApiModelProperty(value = "资源类型", required = true, example = "SCENIC_SPOT")
+    @ApiModelProperty(value = "资源类型，关联字典footprint_resource_type", required = true, example = "SCENIC_SPOT",
+            notes = "可选值：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品")
     @NotBlank(message = "资源类型不能为空")
     private String resourceType;
 
-    @ApiModelProperty(value = "资源ID", required = true, example = "1")
+    @ApiModelProperty(value = "资源ID", required = true, example = "1",
+            notes = "对应资源的ID，同一用户同一资源只保留最新一条足迹")
     @NotNull(message = "资源ID不能为空")
     private Long resourceId;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java
index e8ff874..bdc2f40 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java
@@ -6,18 +6,22 @@ import lombok.Data;
 import javax.validation.constraints.NotBlank;
 
 @Data
-@ApiModel("微信小程序登录请求")
+@ApiModel(value = "微信小程序登录请求", description = "通过wx.login获取code进行登录，首次登录自动注册")
 public class LoginRequest {
-    @ApiModelProperty(value = "微信登录授权码", required = true, example = "0c3NKj000...")
+    @ApiModelProperty(value = "微信登录授权码", required = true, example = "0c3NKj000...",
+            notes = "通过wx.login()获取的临时授权码，后端用此code换取openid/unionid")
     @NotBlank(message = "微信code不能为空")
     private String code;
 
-    @ApiModelProperty(value = "手机号授权码（用于获取手机号）", example = "0c3NKj000...")
+    @ApiModelProperty(value = "手机号授权码（用于获取手机号）", example = "0c3NKj000...",
+            notes = "通过getPhoneNumber按钮获取的code，后端用此code换取用户手机号并绑定")
     private String phoneCode;
 
-    @ApiModelProperty(value = "用户头像URL", example = "https://thirdwx.qlogo.cn/xxx")
+    @ApiModelProperty(value = "用户头像URL", example = "https://thirdwx.qlogo.cn/xxx",
+            notes = "微信头像地址，首次登录时传入用于设置用户头像")
     private String avatar;
 
-    @ApiModelProperty(value = "用户昵称", example = "微信用户")
+    @ApiModelProperty(value = "用户昵称", example = "微信用户",
+            notes = "微信昵称，首次登录时传入用于设置用户昵称")
     private String nickname;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java
index 48d700d..945424d 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/SwitchRoleRequest.java
@@ -7,10 +7,11 @@ import lombok.Data;
 import javax.validation.constraints.NotNull;
 
 @Data
-@ApiModel("角色切换请求")
+@ApiModel(value = "角色切换请求", description = "多角色管理员切换当前活跃角色")
 public class SwitchRoleRequest {
 
     @NotNull(message = "角色ID不能为空")
-    @ApiModelProperty(value = "目标角色ID", required = true)
+    @ApiModelProperty(value = "目标角色ID", required = true,
+            notes = "只能切换到当前管理员已分配的角色，切换后返回新Token和对应菜单权限")
     private Long roleId;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java
index f8d33c8..1c67bb6 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java
@@ -15,10 +15,10 @@ public class TravelerRequest {
     @Size(max = 50, message = "姓名长度不能超过50个字符")
     private String name;
 
-    @ApiModelProperty(value = "出行人类型（无需传入，后端根据出生日期自动判断）", hidden = true)
+    @ApiModelProperty(value = "出行人类型，关联字典traveler_type：ADULT=成人, CHILD=儿童, INFANT=婴儿（无需传入，后端根据birthday自动判断）", hidden = true)
     private String travelerType;   // auto-resolved from birthday
 
-    @ApiModelProperty(value = "证件类型：ID_CARD=身份证 PASSPORT=护照", example = "ID_CARD")
+    @ApiModelProperty(value = "证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照", example = "ID_CARD")
     private String idCardType;     // Default: ID_CARD
 
     @ApiModelProperty(value = "证件号码", example = "110101199001011234")
@@ -29,7 +29,7 @@ public class TravelerRequest {
     @Size(max = 20, message = "手机号长度不能超过20个字符")
     private String phone;
 
-    @ApiModelProperty(value = "性别：0=女 1=男", example = "1")
+    @ApiModelProperty(value = "性别，关联字典gender：0=女, 1=男", example = "1")
     private Integer gender;        // 0=female, 1=male
 
     @ApiModelProperty(value = "出生日期（必填，后端根据此字段自动判断人员类型）", required = true, example = "1990-01-01")

`hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java
index 273a9bc..1e4c1f4 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAvatarRequest.java
@@ -7,13 +7,15 @@ import lombok.Data;
 import javax.validation.constraints.NotBlank;
 
 @Data
-@ApiModel("头像更新请求")
+@ApiModel(value = "头像更新请求", description = "更新管理员头像，需先通过文件服务上传图片")
 public class UpdateAvatarRequest {
 
     @NotBlank(message = "头像URL不能为空")
-    @ApiModelProperty(value = "头像URL", required = true)
+    @ApiModelProperty(value = "头像URL", required = true,
+            notes = "文件服务返回的OSS URL地址")
     private String avatar;
 
-    @ApiModelProperty("文件ID")
+    @ApiModelProperty(value = "文件ID",
+            notes = "文件服务返回的fileId，用于建立文件引用关系，传入后旧头像引用自动解绑")
     private Long fileId;
 }

`hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java b/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java
index a42399c..4e85a2a 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java
@@ -10,16 +10,16 @@ public class UpdateJobRequest {
     @ApiModelProperty(value = "任务名称", example = "同步企微通讯录")
     private String jobName;
 
-    @ApiModelProperty(value = "任务分组", example = "SYSTEM")
+    @ApiModelProperty(value = "任务分组，字典类型：job_group（DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步）", example = "SYSTEM")
     private String jobGroup;
 
-    @ApiModelProperty(value = "调用目标（Bean名称.方法名）", example = "wechatSyncService.syncDepartments")
+    @ApiModelProperty(value = "调用目标（Bean名称.方法名），方法必须是无参公开方法", example = "wechatSyncService.syncDepartments")
     private String invokeTarget;
 
-    @ApiModelProperty(value = "Cron表达式", example = "0 0 2 * * ?")
+    @ApiModelProperty(value = "Cron表达式，标准6位（秒 分 时 日 月 周）", example = "0 0 2 * * ?")
     private String cronExpression;
 
-    @ApiModelProperty(value = "计划执行策略：0=默认 1=立即触发 2=触发一次 3=不触发", example = "0")
+    @ApiModelProperty(value = "计划执行策略，字典类型：job_misfire_policy（DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发）", example = "DEFAULT")
     private String misfirePolicy;
 
     @ApiModelProperty(value = "是否允许并发执行", example = "false")

`hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java b/hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java
index d2b7b8d..aa20c4b 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/controller/AdminNotificationController.java
@@ -45,7 +45,10 @@ public class AdminNotificationController {
 
     // ==================== 事件配置 ====================
 
-    @ApiOperation("获取通知配置列表（按分类分组）")
+    @ApiOperation(value = "获取通知配置列表（按分类分组）", notes = "获取所有通知事件配置，按消息分类（categoryCode）分组返回。"
+            + "每个事件配置包含各通知渠道的开关状态（smsEnabled/inappEnabled/weworkEnabled等）。"
+            + "\n\n**关联字典**：\n"
+            + "- notification_channel（通知渠道）：sms=短信, inapp=站内信, wework=企业微信, miniapp_subscribe=小程序订阅消息, official_account=公众号模板消息\n")
     @GetMapping("/config")
     public Result<Map<String, List<EventConfigVO>>> listConfigs() {
         Map<String, List<NotificationEventConfig>> grouped = configService.listGroupedByCategory();
@@ -66,7 +69,9 @@ public class AdminNotificationController {
         return Result.success(result);
     }
 
-    @ApiOperation("切换通道开关")
+    @ApiOperation(value = "切换通道开关", notes = "切换指定通知事件的某个渠道开关。"
+            + "channel取值：sms/inapp/wework/miniapp_subscribe/official_account。"
+            + "注意：只允许开启渠道，不建议关闭已有渠道。")
     @PutMapping("/config/{id}/toggle")
     public Result<Void> toggleChannel(@PathVariable Long id,
                                        @Valid @RequestBody ChannelToggleRequest request) {
@@ -74,7 +79,10 @@ public class AdminNotificationController {
         return Result.success();
     }
 
-    @ApiOperation("编辑事件配置详情")
+    @ApiOperation(value = "编辑事件配置详情",
+            notes = "更新指定通知事件配置的详细信息，包括模板内容、接收人规则等。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：修改模板内容后会立即影响后续的通知发送。")
     @PutMapping("/config/{id}")
     public Result<Void> updateConfig(@PathVariable Long id,
                                       @Valid @RequestBody EventConfigUpdateRequest request) {
@@ -84,7 +92,11 @@ public class AdminNotificationController {
         return Result.success();
     }
 
-    @ApiOperation("测试发送")
+    @ApiOperation(value = "测试发送",
+            notes = "使用测试数据触发一次通知发送，验证通知配置是否正确。\n"
+                + "会使用预设的测试参数（订单号、产品名等）填充模板。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：需指定 testUserId 或 testAdminId 作为接收人，发送结果可在发送日志中查看。")
     @PostMapping("/config/{id}/test")
     public Result<String> testSend(@PathVariable Long id,
                                     @Valid @RequestBody TestSendRequest request) {
@@ -125,7 +137,10 @@ public class AdminNotificationController {
 
     // ==================== 消息分类 ====================
 
-    @ApiOperation("获取消息分类列表")
+    @ApiOperation(value = "获取消息分类列表",
+            notes = "获取所有通知消息分类，包括分类编码、名称、图标、描述等。\n"
+                + "消息分类用于将通知事件归组管理（如订单消息、系统消息等）。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/categories")
     public Result<List<MessageCategoryVO>> listCategories() {
         List<MessageCategory> categories = categoryService.listAll();
@@ -135,7 +150,10 @@ public class AdminNotificationController {
         return Result.success(voList);
     }
 
-    @ApiOperation("创建消息分类")
+    @ApiOperation(value = "创建消息分类",
+            notes = "创建新的通知消息分类，用于归组管理通知事件。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：分类编码（code）必须唯一，创建后不可修改。")
     @PostMapping("/categories")
     public Result<Void> createCategory(@Valid @RequestBody CategoryRequest request) {
         MessageCategory category = new MessageCategory();
@@ -148,7 +166,10 @@ public class AdminNotificationController {
         return Result.success();
     }
 
-    @ApiOperation("更新消息分类")
+    @ApiOperation(value = "更新消息分类",
+            notes = "更新指定消息分类的名称、图标、描述、排序等信息。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：分类编码（code）不可修改。")
     @PutMapping("/categories/{id}")
     public Result<Void> updateCategory(@PathVariable Long id,
                                         @Valid @RequestBody CategoryRequest request) {
@@ -161,7 +182,10 @@ public class AdminNotificationController {
         return Result.success();
     }
 
-    @ApiOperation("删除消息分类")
+    @ApiOperation(value = "删除消息分类",
+            notes = "删除指定的消息分类。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：如果该分类下有关联的通知事件配置，需先移除关联后才能删除。")
     @DeleteMapping("/categories/{id}")
     public Result<Void> deleteCategory(@PathVariable Long id) {
         categoryService.delete(id);
@@ -170,13 +194,18 @@ public class AdminNotificationController {
 
     // ==================== 发送日志 ====================
 
-    @ApiOperation("查询发送日志")
+    @ApiOperation(value = "查询发送日志", notes = "分页查询通知发送日志，支持按事件编码、渠道、状态等筛选。"
+            + "\n\n**关联字典**：\n"
+            + "- notification_channel（通知渠道）：返回字段channel\n"
+            + "- notification_send_status（发送状态）：返回字段status（SUCCESS=成功, FAILED=失败, SKIPPED=跳过）\n")
     @GetMapping("/logs")
     public Result<PageResult<SendLogVO>> queryLogs(LogQueryRequest request) {
         return Result.success(sendLogService.queryLogs(request));
     }
 
-    @ApiOperation("获取发送统计")
+    @ApiOperation(value = "获取发送统计",
+            notes = "获取通知发送的统计数据，包括总发送数、成功数、失败数、各渠道发送量等。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/logs/stats")
     public Result<SendLogStatsVO> getLogStats() {
         return Result.success(sendLogService.getStats());
@@ -184,7 +213,11 @@ public class AdminNotificationController {
 
     // ==================== 自定义推送 ====================
 
-    @ApiOperation("自定义推送")
+    @ApiOperation(value = "自定义推送",
+            notes = "向指定用户发送自定义通知消息，支持选择推送渠道和目标用户。\n"
+                + "用于运营人员手动推送活动通知、系统公告等。\n\n"
+                + "**权限**：需要管理员登录。\n"
+                + "**注意**：推送记录会记入发送日志。")
     @PostMapping("/custom-push")
     public Result<CustomPushResultVO> customPush(@Valid @RequestBody CustomPushRequest request,
                                                   HttpServletRequest httpRequest) {
@@ -193,7 +226,10 @@ public class AdminNotificationController {
         return Result.success(result);
     }
 
-    @ApiOperation("搜索用户（自定义推送选择目标）")
+    @ApiOperation(value = "搜索用户（自定义推送选择目标）",
+            notes = "按关键词搜索C端用户，用于自定义推送时选择推送目标。\n"
+                + "支持按真实姓名或手机号模糊搜索，最多返回20条结果。\n\n"
+                + "**权限**：需要管理员登录。")
     @GetMapping("/custom-push/users")
     public Result<List<UserSimpleVO>> searchUsersForPush(@RequestParam(required = false) String keyword) {
         LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<User>()

`hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java b/hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java
index 228bb27..2a3ee4f 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/dto/CustomPushRequest.java
@@ -1,5 +1,7 @@
 package com.hulalv.user.notification.dto;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 import javax.validation.constraints.NotBlank;
@@ -10,28 +12,31 @@ import java.util.List;
  * 自定义推送请求
  */
 @Data
+@ApiModel("自定义推送请求")
 public class CustomPushRequest {
 
+    @ApiModelProperty("推送标题")
     @NotBlank(message = "推送标题不能为空")
     private String title;
 
+    @ApiModelProperty("推送内容")
     @NotBlank(message = "推送内容不能为空")
     private String content;
 
-    /** 推送通道: INAPP, SMS, WECHAT_WORK */
+    @ApiModelProperty("推送通道: INAPP/SMS/WECHAT_WORK")
     @NotNull(message = "请选择推送通道")
     private String channel;
 
-    /** 目标类型: ALL_USERS, SPECIFIC_USERS */
+    @ApiModelProperty("目标类型: ALL_USERS/SPECIFIC_USERS")
     @NotNull(message = "请选择目标类型")
     private String targetType;
 
-    /** targetType=SPECIFIC_USERS时必填 */
+    @ApiModelProperty("目标用户ID列表(目标类型为SPECIFIC_USERS时必填)")
     private List<Long> userIds;
 
-    /** 消息分类编码，默认SYSTEM */
+    @ApiModelProperty("消息分类编码，默认SYSTEM")
     private String categoryCode;
 
-    /** 跳转链接（站内信时使用） */
+    @ApiModelProperty("跳转链接(站内信时使用)")
     private String link;
 }

`hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java
index e3cdaf2..495cb3d 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/CustomPushResultVO.java
@@ -1,19 +1,22 @@
 package com.hulalv.user.notification.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 /**
  * 自定义推送结果
  */
 @Data
+@ApiModel("自定义推送结果VO")
 public class CustomPushResultVO {
 
-    /** 推送总数 */
+    @ApiModelProperty("推送总数")
     private int totalCount;
 
-    /** 成功数 */
+    @ApiModelProperty("成功数")
     private int successCount;
 
-    /** 失败数 */
+    @ApiModelProperty("失败数")
     private int failCount;
 }

`hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java
index 8b7e7d1..7434992 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/EventConfigVO.java
@@ -21,7 +21,7 @@ public class EventConfigVO {
     @ApiModelProperty("所属分类名称")
     private String categoryName;
 
-    @ApiModelProperty("站内信开关")
+    @ApiModelProperty("站内信开关（0=关闭, 1=开启）")
     private Integer inappEnabled;
 
     @ApiModelProperty("站内信标题模板")
@@ -33,7 +33,7 @@ public class EventConfigVO {
     @ApiModelProperty("站内信跳转路径模板")
     private String inappLinkTemplate;
 
-    @ApiModelProperty("短信开关")
+    @ApiModelProperty("短信开关（0=关闭, 1=开启）")
     private Integer smsEnabled;
 
     @ApiModelProperty("阿里云短信模板编号")
@@ -42,7 +42,7 @@ public class EventConfigVO {
     @ApiModelProperty("短信签名")
     private String smsSignName;
 
-    @ApiModelProperty("小程序订阅消息开关")
+    @ApiModelProperty("小程序订阅消息开关（0=关闭, 1=开启）")
     private Integer miniappEnabled;
 
     @ApiModelProperty("微信订阅消息模板ID")
@@ -54,7 +54,7 @@ public class EventConfigVO {
     @ApiModelProperty("小程序字段映射JSON")
     private String miniappFieldMapping;
 
-    @ApiModelProperty("公众号模板消息开关")
+    @ApiModelProperty("公众号模板消息开关（0=关闭, 1=开启）")
     private Integer oaEnabled;
 
     @ApiModelProperty("公众号模板ID")
@@ -66,10 +66,10 @@ public class EventConfigVO {
     @ApiModelProperty("公众号字段映射JSON")
     private String oaFieldMapping;
 
-    @ApiModelProperty("企微通知开关")
+    @ApiModelProperty("企微通知开关（0=关闭, 1=开启）")
     private Integer weworkEnabled;
 
-    @ApiModelProperty("企微接收人类型")
+    @ApiModelProperty("企微接收人类型（ROLE=按角色, DEPT=按部门, SPECIFIC=指定人员）")
     private String weworkReceiverType;
 
     @ApiModelProperty("企微消息内容模板")

`hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java
index 8e44260..52c307c 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/SendLogVO.java
@@ -14,7 +14,7 @@ public class SendLogVO {
     @ApiModelProperty("事件编码")
     private String eventCode;
 
-    @ApiModelProperty("通道: INAPP/SMS/MINIAPP/OA/WEWORK")
+    @ApiModelProperty("通道，关联字典notification_channel：INAPP=站内信, SMS=短信, MINIAPP=小程序订阅, OA=公众号模板, WEWORK=企业微信")
     private String channel;
 
     @ApiModelProperty("用户ID")
@@ -38,7 +38,7 @@ public class SendLogVO {
     @ApiModelProperty("关联业务类型")
     private String bizType;
 
-    @ApiModelProperty("发送状态: 0成功 1失败 2跳过")
+    @ApiModelProperty("发送状态，关联字典notification_send_status：0=成功, 1=失败, 2=跳过")
     private Integer status;
 
     @ApiModelProperty("失败原因")

`hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java
index 448b5df..9ad4b62 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/notification/vo/UserSimpleVO.java
@@ -1,18 +1,25 @@
 package com.hulalv.user.notification.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 /**
  * 用户简要信息（自定义推送选择目标用户时使用）
  */
 @Data
+@ApiModel("用户简要信息VO")
 public class UserSimpleVO {
 
+    @ApiModelProperty("用户ID")
     private Long id;
 
+    @ApiModelProperty("真实姓名")
     private String realName;
 
+    @ApiModelProperty("手机号")
     private String phone;
 
+    @ApiModelProperty("头像URL")
     private String avatarUrl;
 }

`hl-user-service/src/main/java/com/hulalv/user/service/SysJobService.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/service/SysJobService.java b/hl-user-service/src/main/java/com/hulalv/user/service/SysJobService.java
index a969c76..3572ae2 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/service/SysJobService.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/service/SysJobService.java
@@ -13,12 +13,17 @@ import com.hulalv.user.entity.SysJob;
 import com.hulalv.user.entity.SysJobLog;
 import com.hulalv.user.mapper.SysJobLogMapper;
 import com.hulalv.user.mapper.SysJobMapper;
+import com.hulalv.user.vo.SysJobLogVO;
+import com.hulalv.user.vo.SysJobVO;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.quartz.*;
+import org.springframework.beans.BeanUtils;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import java.util.stream.Collectors;
+
 @Slf4j
 @Service
 @RequiredArgsConstructor
@@ -28,7 +33,7 @@ public class SysJobService extends ServiceImpl<SysJobMapper, SysJob> {
     private final Scheduler scheduler;
 
     @Transactional
-    public SysJob createJob(CreateJobRequest request) {
+    public SysJobVO createJob(CreateJobRequest request) {
         SysJob job = new SysJob();
         job.setJobName(request.getJobName());
         job.setJobGroup(request.getJobGroup() != null ? request.getJobGroup() : "DEFAULT");
@@ -41,11 +46,11 @@ public class SysJobService extends ServiceImpl<SysJobMapper, SysJob> {
         save(job);
 
         log.info("Job created: name={}, target={}", job.getJobName(), job.getInvokeTarget());
-        return job;
+        return toVO(job);
     }
 
     @Transactional
-    public SysJob updateJob(Long jobId, UpdateJobRequest request) {
+    public SysJobVO updateJob(Long jobId, UpdateJobRequest request) {
         SysJob job = getById(jobId);
         if (job == null) {
             throw new NotFoundException("定时任务不存在");
@@ -68,7 +73,7 @@ public class SysJobService extends ServiceImpl<SysJobMapper, SysJob> {
             createSchedulerJob(job);
         }
 
-        return job;
+        return toVO(job);
     }
 
     @Transactional
@@ -136,23 +141,27 @@ public class SysJobService extends ServiceImpl<SysJobMapper, SysJob> {
         }
     }
 
-    public PageResult<SysJob> listJobs(int page, int pageSize) {
+    public PageResult<SysJobVO> listJobs(int page, int pageSize) {
         Page<SysJob> pageParam = PageUtil.safePage(page, pageSize);
         LambdaQueryWrapper<SysJob> wrapper = new LambdaQueryWrapper<SysJob>()
                 .orderByDesc(SysJob::getCreatedAt)
                 .orderByDesc(SysJob::getJobId);
         Page<SysJob> result = page(pageParam, wrapper);
-        return PageResult.of(result.getRecords(), result.getTotal(), page, pageSize);
+        return PageResult.of(
+                result.getRecords().stream().map(this::toVO).collect(Collectors.toList()),
+                result.getTotal(), page, pageSize);
     }
 
-    public PageResult<SysJobLog> listJobLogs(Long jobId, int page, int pageSize) {
+    public PageResult<SysJobLogVO> listJobLogs(Long jobId, int page, int pageSize) {
         Page<SysJobLog> pageParam = PageUtil.safePage(page, pageSize);
         LambdaQueryWrapper<SysJobLog> wrapper = new LambdaQueryWrapper<SysJobLog>()
                 .eq(SysJobLog::getJobId, jobId)
                 .orderByDesc(SysJobLog::getStartTime)
                 .orderByDesc(SysJobLog::getJobLogId);
         Page<SysJobLog> result = jobLogMapper.selectPage(pageParam, wrapper);
-        return PageResult.of(result.getRecords(), result.getTotal(), page, pageSize);
+        return PageResult.of(
+                result.getRecords().stream().map(this::toLogVO).collect(Collectors.toList()),
+                result.getTotal(), page, pageSize);
     }
 
     void createSchedulerJob(SysJob job) {
@@ -199,4 +208,16 @@ public class SysJobService extends ServiceImpl<SysJobMapper, SysJob> {
             log.error("Failed to remove scheduler job: jobId={}", job.getJobId(), e);
         }
     }
+
+    private SysJobVO toVO(SysJob job) {
+        SysJobVO vo = new SysJobVO();
+        BeanUtils.copyProperties(job, vo);
+        return vo;
+    }
+
+    private SysJobLogVO toLogVO(SysJobLog jobLog) {
+        SysJobLogVO vo = new SysJobLogVO();
+        BeanUtils.copyProperties(jobLog, vo);
+        return vo;
+    }
 }

`hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java b/hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java
index 8bd3d9d..53a203c 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/vo/ContactVO.java
@@ -14,7 +14,7 @@ public class ContactVO {
     @ApiModelProperty(value = "联系方式ID")
     private String id;
 
-    @ApiModelProperty(value = "渠道类型：ABOUT=关于我们 ONLINE_CS=在线客服 PHONE=电话咨询")
+    @ApiModelProperty(value = "渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询")
     private String channelType;
 
     @ApiModelProperty(value = "标题")
@@ -35,7 +35,7 @@ public class ContactVO {
     @ApiModelProperty(value = "排序号")
     private Integer sortOrder;
 
-    @ApiModelProperty(value = "状态：0=下线 1=上线")
+    @ApiModelProperty(value = "状态，关联字典common_status：0=下线, 1=上线")
     private Integer status;
 
     @ApiModelProperty(value = "创建时间")

`hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java b/hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java
index d72a7b3..be9f83a 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/vo/CustomerVO.java
@@ -26,7 +26,7 @@ public class CustomerVO {
     @ApiModelProperty(value = "手机号（不脱敏）")
     private String phone;
 
-    @ApiModelProperty(value = "状态：ACTIVE=正常 DISABLED=禁用")
+    @ApiModelProperty(value = "状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁")
     private String status;
 
     @ApiModelProperty(value = "创建时间")

`hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java b/hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java
index 89620fe..3582c3d 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/vo/LoginLogVO.java
@@ -18,7 +18,7 @@ public class LoginLogVO {
     @ApiModelProperty(value = "管理员名称")
     private String adminName;
 
-    @ApiModelProperty(value = "登录方式：PASSWORD=密码 WECHAT=企微扫码 TWO_FA=二次验证")
+    @ApiModelProperty(value = "登录方式，关联字典login_method：PASSWORD=密码登录, WECHAT_QR=企微扫码登录, TWO_FA=二次验证登录")
     private String loginMethod;
 
     @ApiModelProperty(value = "登录IP地址")
@@ -36,7 +36,7 @@ public class LoginLogVO {
     @ApiModelProperty(value = "登录地区")
     private String location;
 
-    @ApiModelProperty(value = "登录状态：SUCCESS=成功 FAILED=失败")
+    @ApiModelProperty(value = "登录状态，关联字典login_status：SUCCESS=成功, FAILED=失败")
     private String status;
 
     @ApiModelProperty(value = "失败原因")

`hl-user-service/src/main/java/com/hulalv/user/vo/SysJobLogVO.java` (A)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/vo/SysJobLogVO.java b/hl-user-service/src/main/java/com/hulalv/user/vo/SysJobLogVO.java
new file mode 100644
index 0000000..3f031c1
--- /dev/null
+++ b/hl-user-service/src/main/java/com/hulalv/user/vo/SysJobLogVO.java
@@ -0,0 +1,37 @@
+package com.hulalv.user.vo;
+
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
+import java.time.LocalDateTime;
+
+@Data
+@ApiModel("定时任务执行日志")
+public class SysJobLogVO {
+    @ApiModelProperty("日志ID")
+    private Long jobLogId;
+
+    @ApiModelProperty("任务ID")
+    private Long jobId;
+
+    @ApiModelProperty("任务名称")
+    private String jobName;
+
+    @ApiModelProperty("调用目标")
+    private String invokeTarget;
+
+    @ApiModelProperty(value = "执行状态", notes = "字典类型：job_log_status。可选值：SUCCESS=成功, FAIL=失败")
+    private String status;
+
+    @ApiModelProperty("执行结果/异常信息")
+    private String message;
+
+    @ApiModelProperty("开始时间")
+    private LocalDateTime startTime;
+
+    @ApiModelProperty("结束时间")
+    private LocalDateTime endTime;
+
+    @ApiModelProperty("创建时间")
+    private LocalDateTime createdAt;
+}

`hl-user-service/src/main/java/com/hulalv/user/vo/SysJobVO.java` (A)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/vo/SysJobVO.java b/hl-user-service/src/main/java/com/hulalv/user/vo/SysJobVO.java
new file mode 100644
index 0000000..1e84456
--- /dev/null
+++ b/hl-user-service/src/main/java/com/hulalv/user/vo/SysJobVO.java
@@ -0,0 +1,43 @@
+package com.hulalv.user.vo;
+
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
+import java.time.LocalDateTime;
+
+@Data
+@ApiModel("定时任务信息")
+public class SysJobVO {
+    @ApiModelProperty("任务ID")
+    private Long jobId;
+
+    @ApiModelProperty("任务名称")
+    private String jobName;
+
+    @ApiModelProperty(value = "任务分组", notes = "字典类型：job_group。可选值：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步")
+    private String jobGroup;
+
+    @ApiModelProperty("调用目标（Bean名称.方法名）")
+    private String invokeTarget;
+
+    @ApiModelProperty("Cron表达式")
+    private String cronExpression;
+
+    @ApiModelProperty(value = "计划执行策略", notes = "字典类型：job_misfire_policy。可选值：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发")
+    private String misfirePolicy;
+
+    @ApiModelProperty("是否允许并发执行")
+    private Boolean concurrent;
+
+    @ApiModelProperty(value = "任务状态", notes = "字典类型：job_status。可选值：ACTIVE=启用, PAUSED=已暂停")
+    private String status;
+
+    @ApiModelProperty("备注")
+    private String remark;
+
+    @ApiModelProperty("创建时间")
+    private LocalDateTime createdAt;
+
+    @ApiModelProperty("更新时间")
+    private LocalDateTime updatedAt;
+}

`hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java` (M)

diff --git a/hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java b/hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java
index cb64d33..bbc0ede 100644
--- a/hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java
+++ b/hl-user-service/src/main/java/com/hulalv/user/vo/UserVO.java
@@ -29,20 +29,20 @@ public class UserVO {
     @ApiModelProperty(value = "真实手机号（仅内部接口返回，用于订单预填）", hidden = true)
     private String rawPhone; // 真实手机号（仅内部接口返回，用于订单预填）
 
-    @ApiModelProperty(value = "状态：ACTIVE=正常 DISABLED=禁用")
+    @ApiModelProperty(value = "状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁")
     private String status;
 
     // 个人信息字段(用于编辑"本人"出行人信息)
     @ApiModelProperty(value = "真实姓名")
     private String realName;
 
-    @ApiModelProperty(value = "证件类型：ID_CARD=身份证 PASSPORT=护照")
+    @ApiModelProperty(value = "证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照")
     private String idCardType;
 
     @ApiModelProperty(value = "证件号码")
     private String idCardNo;
 
-    @ApiModelProperty(value = "性别：0=女 1=男")
+    @ApiModelProperty(value = "性别，关联字典gender：0=女, 1=男")
     private Integer gender;
 
     @ApiModelProperty(value = "出生日期")

`hl-user-service/src/test/java/com/hulalv/user/service/SysJobServiceTest.java` (M)

diff --git a/hl-user-service/src/test/java/com/hulalv/user/service/SysJobServiceTest.java b/hl-user-service/src/test/java/com/hulalv/user/service/SysJobServiceTest.java
index 64d284e..853dcd1 100644
--- a/hl-user-service/src/test/java/com/hulalv/user/service/SysJobServiceTest.java
+++ b/hl-user-service/src/test/java/com/hulalv/user/service/SysJobServiceTest.java
@@ -10,6 +10,8 @@ import com.hulalv.user.dto.UpdateJobRequest;
 import com.hulalv.user.entity.SysJob;
 import com.hulalv.user.entity.SysJobLog;
 import com.hulalv.user.mapper.SysJobLogMapper;
+import com.hulalv.user.vo.SysJobLogVO;
+import com.hulalv.user.vo.SysJobVO;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
@@ -60,7 +62,7 @@ class SysJobServiceTest {
 
         doReturn(true).when(sysJobService).save(any(SysJob.class));
 
-        SysJob result = sysJobService.createJob(request);
+        SysJobVO result = sysJobService.createJob(request);
 
         assertNotNull(result);
         assertEquals("新任务", result.getJobName());
@@ -82,7 +84,7 @@ class SysJobServiceTest {
 
         doReturn(true).when(sysJobService).save(any(SysJob.class));
 
-        SysJob result = sysJobService.createJob(request);
+        SysJobVO result = sysJobService.createJob(request);
 
         assertEquals("SYSTEM", result.getJobGroup());
         assertEquals("FIRE_ONCE", result.getMisfirePolicy());
@@ -99,7 +101,7 @@ class SysJobServiceTest {
         doReturn(testJob).when(sysJobService).getById(3001L);
         doReturn(true).when(sysJobService).updateById(any(SysJob.class));
 
-        SysJob result = sysJobService.updateJob(3001L, request);
+        SysJobVO result = sysJobService.updateJob(3001L, request);
 
         assertEquals("更新任务名", result.getJobName());
         assertEquals("0 0/10 * * * ?", result.getCronExpression());
@@ -121,7 +123,7 @@ class SysJobServiceTest {
         when(scheduler.deleteJob(jobKey)).thenReturn(true);
         when(scheduler.scheduleJob(any(JobDetail.class), any(Trigger.class))).thenReturn(null);
 
-        SysJob result = sysJobService.updateJob(3001L, request);
+        SysJobVO result = sysJobService.updateJob(3001L, request);
 
         assertNotNull(result);
         verify(scheduler).deleteJob(jobKey);
@@ -248,10 +250,11 @@ class SysJobServiceTest {
 
         doReturn(mockPage).when(sysJobService).page(any(Page.class), any());
 
-        PageResult<SysJob> result = sysJobService.listJobs(1, 10);
+        PageResult<SysJobVO> result = sysJobService.listJobs(1, 10);
 
         assertNotNull(result);
         assertEquals(1, result.getRecords().size());
+        assertInstanceOf(SysJobVO.class, result.getRecords().get(0));
     }
 
     @Test
@@ -268,9 +271,10 @@ class SysJobServiceTest {
         when(jobLogMapper.selectPage(any(Page.class), any(LambdaQueryWrapper.class)))
                 .thenReturn(mockPage);
 
-        PageResult<SysJobLog> result = sysJobService.listJobLogs(3001L, 1, 10);
+        PageResult<SysJobLogVO> result = sysJobService.listJobLogs(3001L, 1, 10);
 
         assertNotNull(result);
         assertEquals(1, result.getRecords().size());
+        assertInstanceOf(SysJobLogVO.class, result.getRecords().get(0));
     }
 }

1.8 MiB 原始文件 Blame 文件历史 Unescape Escape

接口变更记录

提交信息

变更文件总览

Controller 接口变更

hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java (M)

hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java (M)

hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java (M)

hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java (M)

hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java (M)

hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java (M)

hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java (M)

hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java (M)

hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java (M)

hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java (M)

hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java (M)

hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java (M)

hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java (M)

hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java (M)

hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java (M)

hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java (M)

hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java (M)

hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java (M)

hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java (M)

hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java (M)

hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java (M)

hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java (M)

hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java (M)

hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java (M)

hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java (M)

1.8 MiB

原始文件 Blame 文件历史

`hl-callback-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java` (M)

`hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java` (M)

`hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java` (M)

`hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java` (M)

`hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java` (M)

`hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java` (M)

`hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java` (M)

`hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java` (M)

`hl-file-service/src/main/java/com/hulalv/file/controller/InternalFileController.java` (M)

`hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java` (M)

`hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java` (M)

`hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java` (M)

`hl-guide-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java` (M)

`hl-guide-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java` (M)

`hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java` (M)

`hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java` (M)

`hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java` (M)

`hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java` (M)

`hl-material-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java` (M)

`hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java` (M)

`hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java` (M)

`hl-material-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java` (M)

`hl-monitor-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBadgeController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHomeController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpLikeController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java` (M)

`hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java` (M)

`hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java` (M)