chore(s8): mark legacy watch rule endpoints deprecated

server/Plugins/Admin.NET.Plugin.AiDOP/Controllers/S8/AdoS8ConfigWatchRulesController.cs

@@ -1,5 +1,7 @@
+using System.Security.Claims;
 using Admin.NET.Plugin.AiDOP.Entity.S8;
 using Admin.NET.Plugin.AiDOP.Service.S8;
+using Microsoft.Extensions.Logging;
 
 namespace Admin.NET.Plugin.AiDOP.Controllers.S8;
 
@@ -8,38 +10,71 @@ namespace Admin.NET.Plugin.AiDOP.Controllers.S8;
 [NonUnify]
 public class AdoS8ConfigWatchRulesController : ControllerBase
 {
+    private const string LegacyHeaderUseInstead = "PUT /api/aidop/s8/config/watch-rules/{id}/params";
+
     private readonly S8WatchRuleService _svc;
+    private readonly ILogger<AdoS8ConfigWatchRulesController> _logger;
 
-    public AdoS8ConfigWatchRulesController(S8WatchRuleService svc) => _svc = svc;
+    public AdoS8ConfigWatchRulesController(
+        S8WatchRuleService svc,
+        ILogger<AdoS8ConfigWatchRulesController> logger)
+    {
+        _svc = svc;
+        _logger = logger;
+    }
 
     [HttpGet]
     public async Task<IActionResult> ListAsync([FromQuery] long tenantId = 1, [FromQuery] long factoryId = 1) =>
         Ok(await _svc.ListAsync(tenantId, factoryId));
 
+    /// <summary>
+    /// Legacy endpoint. Rule configuration UI must use PUT /{id}/params.
+    /// 保留兼容历史脚本/集成调用，但响应 header 与日志会标记为 deprecated。
+    /// </summary>
+    [Obsolete("Legacy full-create endpoint. Use PUT /api/aidop/s8/config/watch-rules/{id}/params for safe params editing.")]
     [HttpPost]
     public async Task<IActionResult> CreateAsync([FromBody] AdoS8WatchRule body)
     {
+        MarkLegacyDeprecated("POST /api/aidop/s8/config/watch-rules");
         try { return Ok(await _svc.CreateAsync(body)); }
         catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
     }
 
+    /// <summary>
+    /// Legacy endpoint. Rule configuration UI must use PUT /{id}/params.
+    /// 保留兼容历史脚本/集成调用，但响应 header 与日志会标记为 deprecated。
+    /// </summary>
+    [Obsolete("Legacy full-update endpoint. Use PUT /api/aidop/s8/config/watch-rules/{id}/params for safe params editing.")]
     [HttpPut("{id:long}")]
     public async Task<IActionResult> UpdateAsync(long id, [FromBody] AdoS8WatchRule body)
     {
+        MarkLegacyDeprecated($"PUT /api/aidop/s8/config/watch-rules/{id}", id);
         try { return Ok(await _svc.UpdateAsync(id, body)); }
         catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
     }
 
+    /// <summary>
+    /// Legacy endpoint. Rule configuration UI must use PUT /{id}/params.
+    /// 保留兼容历史脚本/集成调用，但响应 header 与日志会标记为 deprecated。
+    /// </summary>
+    [Obsolete("Legacy delete endpoint. Use PUT /api/aidop/s8/config/watch-rules/{id}/params for safe params editing.")]
     [HttpDelete("{id:long}")]
     public async Task<IActionResult> DeleteAsync(long id)
     {
+        MarkLegacyDeprecated($"DELETE /api/aidop/s8/config/watch-rules/{id}", id);
         await _svc.DeleteAsync(id);
         return Ok();
     }
 
+    /// <summary>
+    /// Legacy endpoint. Rule configuration UI must use PUT /{id}/params.
+    /// 保留兼容历史脚本/集成调用，但响应 header 与日志会标记为 deprecated。
+    /// </summary>
+    [Obsolete("Legacy test endpoint. Use PUT /api/aidop/s8/config/watch-rules/{id}/params for safe params editing.")]
     [HttpPost("{id:long}/test")]
     public async Task<IActionResult> TestAsync(long id)
     {
+        MarkLegacyDeprecated($"POST /api/aidop/s8/config/watch-rules/{id}/test", id);
         try { return Ok(await _svc.TestAsync(id)); }
         catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
     }
@@ -55,4 +90,27 @@ public class AdoS8ConfigWatchRulesController : ControllerBase
         try { return Ok(await _svc.UpdateParamsAsync(id, body)); }
         catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
     }
+
+    /// <summary>
+    /// 旧端点 deprecated 收口：写入响应 header 标记 + 结构化 warning 日志，便于运行期识别 legacy 调用。
+    /// 不阻断调用，不改返回结构。
+    /// </summary>
+    private void MarkLegacyDeprecated(string endpoint, long? ruleId = null)
+    {
+        // 响应 header — Headers 在响应已开始发送后会抛 InvalidOperationException，此处守卫一下避免污染主调用。
+        var headers = Response.Headers;
+        if (!headers.ContainsKey("X-AiDOP-Deprecated"))
+            headers["X-AiDOP-Deprecated"] = "true";
+        if (!headers.ContainsKey("X-AiDOP-Use-Instead"))
+            headers["X-AiDOP-Use-Instead"] = LegacyHeaderUseInstead;
+
+        var userId = User?.FindFirst("UserId")?.Value
+                     ?? User?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
+        var tenantId = HttpContext?.Request?.Query["tenantId"].ToString();
+        var factoryId = HttpContext?.Request?.Query["factoryId"].ToString();
+
+        _logger.LogWarning(
+            "legacy_watch_rule_endpoint endpoint={Endpoint} ruleId={RuleId} userId={UserId} tenantId={TenantId} factoryId={FactoryId} useInstead={UseInstead}",
+            endpoint, ruleId, userId, tenantId, factoryId, LegacyHeaderUseInstead);
+    }
 }