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

using Admin.NET.Plugin.AiDOP.Infrastructure.S8;
using Admin.NET.Plugin.AiDOP.Const.S8;
using System.Security.Claims;
using Admin.NET.Plugin.AiDOP.Entity.S8;
using Admin.NET.Plugin.AiDOP.Infrastructure;
using Admin.NET.Plugin.AiDOP.Service.S8;
using Admin.NET.Plugin.AiDOP.Service.S8.Rules;
using Microsoft.Extensions.Logging;

namespace Admin.NET.Plugin.AiDOP.Controllers.S8;

[ApiController]
[Route("api/aidop/s8/config/watch-rules")]
[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;
    private readonly S8TrustedScopeResolver _scope;

    public AdoS8ConfigWatchRulesController(
        S8WatchRuleService svc,
        ILogger<AdoS8ConfigWatchRulesController> logger,
        S8TrustedScopeResolver scope)
    {
        _svc = svc;
        _logger = logger;
        _scope = scope;
    }

    [HttpGet]
    [S8Permission(S8PermissionCatalog.ConfigRead)]
    public async Task<IActionResult> ListAsync([FromQuery] long tenantId = 1, [FromQuery] long factoryId = 1)
    {
        // Compatibility-only. Security scope is resolved server-side.
        _ = tenantId; _ = factoryId;
        var scope = await _scope.ResolveAsync();
        return Ok(await _svc.ListAsync(scope.TenantId, scope.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]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    public async Task<IActionResult> CreateAsync([FromBody] AdoS8WatchRule body)
    {
        MarkLegacyDeprecated("POST /api/aidop/s8/config/watch-rules");
        try { return Ok(await _svc.CreateAsync(body, await _scope.ResolveAsync())); }
        catch (S8NotFoundException) { return NotFound(); }
        catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
    }

    /// <summary>
    /// Legacy endpoint. Rule configuration UI must use PUT /{id}/params.
    /// 保留兼容历史脚本/集成调用，但响应 header 与日志会标记为 deprecated。
    /// </summary>
    // ================================================================================
    // S8-STEP6E-CFG-WATCH-FIX-AND-SAFE-CERT-1：本入口已退役 → 410 Gone。
    //
    // 它是整实体更新，会连带把 13 个 scheduler-owned 运行时列暴露给客户端
    //（lock_token / lock_until / paused_until / next_run_at / last_* / consecutive_failure_count），
    // 足以窃取租约、制造重复执行、静默停掉监控、伪造调度审计。详见 S8WatchRuleService.UpdateAsync 注释。
    //
    // 选 410 而非 400/404：语义是「该能力曾经存在、现已永久退役」。
    // 400 会暗示「改对入参还能存」，404 会暗示「换个 Id 还能存」，都与事实不符。
    //
    // ⚠️ 不再调用 _scope.ResolveAsync()：写能力已退役，不该为构造一个用不到的 scope 去读组织库；
    //    这同时保证 DB access = 0，并让工厂组织 0 个/多个的租户也稳定得到 410 而非作用域错误。
    // ⚠️ catch 顺序：S8WriteRetiredException 必须排在 S8NotFoundException / S8BizException 之前。
    // GET 与 /params /schedule /run-now /pause /resume 全部不受影响。
    // ================================================================================
    [Obsolete("Retired full-update endpoint. Use PUT /api/aidop/s8/config/watch-rules/{id}/params or /schedule.")]
    [HttpPut("{id:long}")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    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, RetiredWriteScope)); }
        catch (S8WriteRetiredException ex)
        {
            return StatusCode(Microsoft.AspNetCore.Http.StatusCodes.Status410Gone, new { message = ex.Message });
        }
        catch (S8NotFoundException) { return NotFound(); }
        catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
    }

    /// <summary>
    /// 写能力已永久退役：不得为了构造一个不会被使用的 scope 而读取组织库。
    /// Service 写方法必须在读取该占位值或访问任何仓储前抛 S8WriteRetiredException。
    /// （与 CFG_ALERT 的 RetiredWriteScope 同一模式。）
    /// </summary>
    private static readonly S8TrustedScope RetiredWriteScope = new(0, 0);

    /// <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}")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    public async Task<IActionResult> DeleteAsync(long id)
    {
        MarkLegacyDeprecated($"DELETE /api/aidop/s8/config/watch-rules/{id}", id);
        try { await _svc.DeleteAsync(id, await _scope.ResolveAsync()); }
        catch (S8NotFoundException) { return NotFound(); }
        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")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    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, await _scope.ResolveAsync())); }
        catch (S8NotFoundException) { return NotFound(); }
        catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
    }

    /// <summary>
    /// S8-RULE01-INTEGRATION-PREVIEW-1：只读预演 —— 「这条规则现在启用会命中什么」。
    ///
    /// 在此之前想回答这个问题只能真把规则 enabled=true 然后等调度器跑，
    /// 对 Rule 01 而言那意味着一次性生成 28 条真实异常单，而验证只需要 1 条。
    /// 本端点补上这个中间档位：走**与生产完全相同**的 Gateway → Provider → Evaluator 链，
    /// 但不写 detection_log / exception / rule_detection_state，不改规则任何列，不发通知。
    ///
    /// 用 GET 而非 POST 是刻意的：它是一次查询，没有副作用，
    /// 用 POST 会让调用方以为「点了就会发生什么」。
    ///
    /// 权限沿用 ConfigWatchRule（能配规则的人才能预演），作用域由服务端盖章。
    /// </summary>
    [HttpGet("{id:long}/preview")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    public async Task<IActionResult> PreviewAsync(long id, [FromServices] S8WatchRulePreviewService preview)
    {
        try { return Ok(await preview.PreviewAsync(id, await _scope.ResolveAsync())); }
        catch (S8NotFoundException) { return NotFound(); }
        catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
        catch (S8RuleEvaluatorException ex) { return BadRequest(new { reason = ex.Reason, message = ex.Message }); }
    }

    /// <summary>
    /// S8-RULE-GOVERNANCE-BATCH1：运行参数的**部分更新**。
    ///
    /// <para>只接受该规则的代码定义所声明的运行参数白名单
    /// （轮询间隔 / 抗抖次数 / 宽限分钟 / 严重度 / 部门兜底），未提供的字段保持原值。</para>
    ///
    /// <para><b>不再接受</b> params_json 原文与任何判定语义字段 —— 那些由代码定义，
    /// 出现在载荷里会得到 400 而不是被静默忽略。<b>也不再接受 enabled</b>，
    /// 启停请用 <c>/enable</c> 与 <c>/disable</c>。</para>
    ///
    /// <para>路由暂时保留 <c>/params</c> 以免与前端一次性大改耦合；
    /// 前端适配排在 Batch 4。</para>
    /// </summary>
    [HttpPut("{id:long}/params")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    public async Task<IActionResult> UpdateParamsAsync(long id, [FromBody] S8RuleParametersPayload body)
    {
        try { return Ok(await _svc.UpdateParametersAsync(id, body, await _scope.ResolveAsync())); }
        catch (S8NotFoundException) { return NotFound(); }
        catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
    }

    /// <summary>
    /// 启用规则。<b>与参数写入完全分离</b>：本端点只写 enabled 与下次执行时间，
    /// 不触碰 params_json、不触碰任何参数列、不触碰定义投影列。
    ///
    /// <para>这条分离是 G1 的结构性修复：此前启停与 params_json 共用一个写入口，
    /// 一次「只想关个开关」的调用就会把规则的全部业务配置抹成 NULL。</para>
    ///
    /// <para>幂等：重复启用不产生写入。</para>
    /// </summary>
    [HttpPost("{id:long}/enable")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    public async Task<IActionResult> EnableAsync(long id)
    {
        try { return Ok(await _svc.EnableAsync(id, await _scope.ResolveAsync())); }
        catch (S8NotFoundException) { return NotFound(); }
        catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
    }

    /// <summary>
    /// 停用规则。只写 enabled；幂等。
    /// <b>刻意不过 Enable Gate</b>：数据集出问题之后仍然必须能把规则关掉。
    /// </summary>
    [HttpPost("{id:long}/disable")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    public async Task<IActionResult> DisableAsync(long id)
    {
        try { return Ok(await _svc.DisableAsync(id, await _scope.ResolveAsync())); }
        catch (S8NotFoundException) { return NotFound(); }
        catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
    }

    /// <summary>
    /// S8-SCHED-FRONTEND-1：调度参数安全更新（仅 poll_interval_seconds / trigger_count_required / recover_count_required）。
    /// S8-RULE-GOVERNANCE-BATCH1：已委托到统一的参数写入路径，语义与 <c>/params</c> 一致。
    /// </summary>
    [HttpPut("{id:long}/schedule")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    public async Task<IActionResult> UpdateScheduleAsync(long id, [FromBody] S8WatchRuleSchedulePayload body)
    {
        try { return Ok(await _svc.UpdateScheduleAsync(id, body, await _scope.ResolveAsync())); }
        catch (S8NotFoundException) { return NotFound(); }
        catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
    }

    /// <summary>S8-SCHED-FRONTEND-1：立即执行一次，next_run_at 置为 NOW，由下一 tick 拾取。</summary>
    [HttpPost("{id:long}/run-now")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    public async Task<IActionResult> RunNowAsync(long id)
    {
        try { return Ok(await _svc.RunNowAsync(id, await _scope.ResolveAsync())); }
        catch (S8NotFoundException) { return NotFound(); }
        catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
    }

    /// <summary>S8-SCHED-FRONTEND-1：手工暂停，paused_until 置为远未来哨兵 + pause_reason=MANUAL_PAUSED。</summary>
    [HttpPost("{id:long}/pause")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    public async Task<IActionResult> PauseAsync(long id)
    {
        try { return Ok(await _svc.PauseAsync(id, await _scope.ResolveAsync())); }
        catch (S8NotFoundException) { return NotFound(); }
        catch (S8BizException ex) { return BadRequest(new { message = ex.Message }); }
    }

    /// <summary>S8-SCHED-FRONTEND-1：恢复，清 paused_until / pause_reason / last_error / consecutive_failure_count，next_run_at = NOW。</summary>
    [HttpPost("{id:long}/resume")]
    [S8Permission(S8PermissionCatalog.ConfigWatchRule)]
    public async Task<IActionResult> ResumeAsync(long id)
    {
        try { return Ok(await _svc.ResumeAsync(id, await _scope.ResolveAsync())); }
        catch (S8NotFoundException) { return NotFound(); }
        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);
    }
}