feat(library): 作业详情显示维护状态与人工处置

发布作业详情在目标仍被维护时返回 maintenance(持有作业、入口状态、目标身份、
备注、是否已释放)与 next_step;作业本身继续带 operation_id/attempt_epoch/预备份/
目标快照与错误说明,能定位到"哪个意图、哪份基线、哪个目标"。

不提供强制成功/强制开门入口:缺归属证据的收尾保持维护锁定,按预备份与校验证据
人工核验后再放行(用户已接受的可用性边界)。页面同时提示发布/恢复后旧分页游标
失效、需要刷新重新分页。
This commit is contained in:
姚章浩
2026-11-01 17:21:42 +08:00
parent f4bd1980bf
commit 0df0e3cb1e
3 changed files with 115 additions and 1 deletions
+32 -1
View File
@@ -853,7 +853,38 @@ func libraryJobDetailHandler(w http.ResponseWriter, r *http.Request, config Conf
writeJSON(w, http.StatusNotFound, map[string]any{"available": false, "reason": "作业不存在"})
return
}
writeJSON(w, http.StatusOK, map[string]any{"available": true, "job": job})
detail := map[string]any{"available": true, "job": job}
// 只读诊断:明确"目标现在被谁按着、入口是什么状态、下一步该怎么做"。
// 这里刻意不提供任何"强制成功/强制开门"的入口:缺归属证据的作业必须停在
// held,由人工按预备份与校验证据处置(已接受的可用性边界)。
if maintenanceStore, ok := config.Store.(interface {
LibraryMaintenanceOf(ctx context.Context, scope string) (*postgresstore.LibraryMaintenance, error)
}); ok {
maintenance, maintenanceErr := maintenanceStore.LibraryMaintenanceOf(r.Context(), job.Scope)
if maintenanceErr != nil || maintenance == nil {
writeJSON(w, http.StatusOK, detail)
return
}
held := maintenance.ReleasedAt == nil
detail["maintenance"] = map[string]any{
"held": held,
"owner_job_id": maintenance.OwnerJobID,
"owner_is_job": maintenance.OwnerJobID == job.ID,
"state": maintenance.State,
"ingress": maintenance.IngressState,
"target_identity": maintenance.TargetIdentity,
"note": maintenance.Note,
"acquired_at": maintenance.AcquiredAt,
"released": !held,
}
if held && job.State == governance.LibraryJobFailed {
detail["next_step"] = "内容可能已写入并通过校验,但收尾未完成:目标仍处于维护、入口未开。按本作业的预备份与校验证据人工核验后再放行;本接口不提供强制成功。"
}
}
if _, ok := detail["next_step"]; !ok && job.State == governance.LibraryJobFailed && job.Recovery != "" {
detail["next_step"] = job.Recovery
}
writeJSON(w, http.StatusOK, detail)
}
// librarySyncEnqueue 是生产同步的唯一入口:闸口未齐时**不建作业**,直接说明缺项。
@@ -0,0 +1,75 @@
package httpapi
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
"knowledge-governance/internal/governance"
postgresstore "knowledge-governance/internal/platform/postgres"
)
type r13HeldDetailStore struct {
fakeLibraryStore
maintenance *postgresstore.LibraryMaintenance
job governance.LibraryJob
}
func (s *r13HeldDetailStore) LibraryJob(_ context.Context, id string) (governance.LibraryJob, error) {
job := s.job
job.ID = id
return job, nil
}
func (s *r13HeldDetailStore) LibraryMaintenanceOf(context.Context, string) (*postgresstore.LibraryMaintenance, error) {
return s.maintenance, nil
}
// 已接受的边界:缺归属证据的作业停在 held,页面/接口必须给出可核对的 job/operation/目标
// 与阻断原因,并且**不能**提供"强制成功/强制开门"的动作。
func TestR13HeldJobDetailExplainsManualRecovery(t *testing.T) {
store := &r13HeldDetailStore{maintenance: &postgresstore.LibraryMaintenance{
Scope: "internal", OwnerJobID: "job-held", State: "needs_restore",
IngressState: "open", TargetIdentity: "scope=internal", Note: "内容已验证,但收尾未完成",
Services: []string{"app"},
}}
store.job = governance.LibraryJob{
Scope: "internal", Kind: governance.LibraryJobSync, State: governance.LibraryJobFailed,
Stage: "finalize", OperationID: "op-r13", AttemptEpoch: 2,
SnapshotID: "backup-r13", TargetSnapshotID: "target-r13",
Error: "内容已验证,但收尾未完成", Recovery: "预备份保留;按归档人工核验",
}
request := httptest.NewRequest(http.MethodGet, "/api/v1/library/jobs/job-held", nil)
request.SetPathValue("id", "job-held")
recorder := httptest.NewRecorder()
libraryJobDetailHandler(recorder, request, Config{Store: store})
if recorder.Code != http.StatusOK {
t.Fatalf("status = %d body=%s", recorder.Code, recorder.Body.String())
}
var body map[string]any
if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
t.Fatal(err)
}
job, _ := body["job"].(map[string]any)
if job["operation_id"] != "op-r13" || job["attempt_epoch"] != float64(2) ||
job["snapshot_id"] != "backup-r13" || job["target_snapshot_id"] != "target-r13" {
t.Fatalf("作业身份/证据不完整:%v", job)
}
maintenance, _ := body["maintenance"].(map[string]any)
if maintenance["held"] != true || maintenance["owner_is_job"] != true || maintenance["state"] != "needs_restore" {
t.Fatalf("维护状态没有暴露:%v", maintenance)
}
step, _ := body["next_step"].(string)
if !strings.Contains(step, "维护") || !strings.Contains(step, "人工") {
t.Fatalf("下一步没有指向人工核验:%q", step)
}
raw := strings.ToLower(recorder.Body.String())
for _, banned := range []string{"force_success", "force-open", "force_open", "ignore_unknown", "skip_verify"} {
if strings.Contains(raw, banned) {
t.Fatalf("诊断接口出现了强制动作:%s", banned)
}
}
}
+8
View File
@@ -444,8 +444,16 @@ export function MaintenanceCard({
<strong>恢复错误</strong>
<p>{summary.recoveryError}</p>
{summary.recoveryNote ? <p>处理记录:{summary.recoveryNote}</p> : null}
<p>
内容可能已写入并通过校验,但收尾没有完成:目标保持维护、入口未开。请按本作业的预备份与校验证据人工核验后再放行;
页面不提供“强制成功”,也不会因为“看起来已经写进去了”就开门。
</p>
</div>
) : null}
<p className="rel-scope-note">
发布或恢复完成后,Wiki 与日志页面需要刷新再翻页:发布前的分页游标在发布后失效(本地编号会被重新编排),
用旧标签页继续翻页会得到错位的结果,这不是数据损坏。
</p>
{canWrite && summary.canRecover && record ? (
<button type="button" className="rel-secondary" onClick={() => onRecover(record.owner_job_id)}>
按预备份恢复