docs(device): document adapter service contracts

yeg

2026-08-26 a9e3435464f86a50ffa81a16ef92e47734adef6e

 ruoyi-admin/src/main/java/com/ruoyi/web/controller/device/DeviceAdapterController.java

@@ -31,6 +31,7 @@

    @PreAuthorize("@ss.hasPermi('system:deviceAdapter:list')")
    @GetMapping("/list")
    /** 分页查询适配器配置及其最近运行状态。 */
    public TableDataInfo list()
    {
        startPage();
@@ -39,11 +40,13 @@

    @PreAuthorize("@ss.hasPermi('system:deviceAdapter:query')")
    @GetMapping("/{adapterId}")
    /** 查询指定适配器详情；适配器必须存在。 */
    public AjaxResult getInfo(@PathVariable Long adapterId) { return success(service.selectById(adapterId)); }

    @PreAuthorize("@ss.hasPermi('system:deviceAdapter:add')")
    @Log(title = "设备适配器实例", businessType = BusinessType.INSERT)
    @PostMapping
    /** 新增默认禁用的只读适配器配置。 */
    public AjaxResult add(@Validated @RequestBody TDeviceAdapter adapter)
    {
        adapter.setCreateBy(getUsername());
@@ -53,6 +56,7 @@
    @PreAuthorize("@ss.hasPermi('system:deviceAdapter:edit')")
    @Log(title = "设备适配器实例", businessType = BusinessType.UPDATE)
    @PutMapping
    /** 修改适配器配置；启用实例会同步替换运行时连接。 */
    public AjaxResult edit(@Validated @RequestBody TDeviceAdapter adapter)
    {
        adapter.setUpdateBy(getUsername());
@@ -62,6 +66,7 @@
    @PreAuthorize("@ss.hasPermi('system:deviceAdapter:changeStatus')")
    @Log(title = "设备适配器实例启停", businessType = BusinessType.UPDATE)
    @PutMapping("/{adapterId}/status")
    /** 启用或停用适配器；启用前配置必须通过只读校验。 */
    public AjaxResult changeStatus(@PathVariable Long adapterId, @RequestBody StatusCommand command)
    {
        return toAjax(service.changeStatus(adapterId, command.enabled(), getUsername()));
@@ -70,10 +75,12 @@
    @PreAuthorize("@ss.hasPermi('system:deviceAdapter:discover')")
    @Log(title = "设备适配器发现", businessType = BusinessType.OTHER)
    @PostMapping("/{adapterId}/discover")
    /** 执行一次 getdevinfo 与实时 inquire，并返回本轮发现摘要。 */
    public AjaxResult discover(@PathVariable Long adapterId) { return success(service.discover(adapterId)); }

    @PreAuthorize("@ss.hasPermi('system:deviceAdapter:list')")
    @GetMapping("/{adapterId}/channels")
    /** 查询适配器已持久化的通道事实，不因本轮缺失而删除。 */
    public AjaxResult channels(@PathVariable Long adapterId) { return success(service.selectChannels(adapterId)); }

    public record StatusCommand(boolean enabled) { }