feat: 删章重排级联、章号侧车编排（伏笔/快照/向量）及接口与前端

Made-with: Cursor

Author: shenminglinyi

application/core/services/chapter_service.py

@@ -1,5 +1,5 @@
 """Chapter 应用服务"""
-from typing import List, Optional
+from typing import List, Optional, Any
 from datetime import datetime
 import re
 from domain.novel.entities.chapter import Chapter, ChapterStatus
@@ -20,18 +20,21 @@ def __init__(
         self,
         chapter_repository: ChapterRepository,
         novel_repository: NovelRepository,
-        chapter_review_repository=None
+        chapter_review_repository=None,
+        chapter_renumber_coordinator: Any = None,
     ):
         """初始化服务
 
         Args:
             chapter_repository: Chapter 仓储
             novel_repository: Novel 仓储
             chapter_review_repository: Chapter Review 仓储（可选）
+            chapter_renumber_coordinator: 删章后伏笔/快照/向量等侧车数据章号重排（可选）
         """
         self.chapter_repository = chapter_repository
         self.novel_repository = novel_repository
         self.chapter_review_repository = chapter_review_repository
+        self._chapter_renumber_coordinator = chapter_renumber_coordinator
 
     def update_chapter_content(
         self,
@@ -91,7 +94,19 @@ def delete_chapter(self, chapter_id: str) -> None:
         Args:
             chapter_id: 章节 ID
         """
+        chapter = self.chapter_repository.get_by_id(ChapterId(chapter_id))
+        if chapter is None:
+            return
+        novel_id = (
+            chapter.novel_id.value
+            if hasattr(chapter.novel_id, "value")
+            else chapter.novel_id
+        )
+        deleted_number = chapter.number
         self.chapter_repository.delete(ChapterId(chapter_id))
+        coordinator = self._chapter_renumber_coordinator
+        if coordinator is not None:
+            coordinator.on_chapter_deleted(novel_id, deleted_number)
 
     def get_chapter_by_novel_and_number(
         self,

application/novel/chapter_renumber/__init__.py

@@ -0,0 +1,17 @@
+"""删章后章号侧车数据（伏笔、快照 JSON、向量等）重排编排。"""
+
+from application.novel.chapter_renumber.coordinator import (
+    ChapterRenumberContext,
+    ChapterRenumberCoordinator,
+    ChapterRenumberExtension,
+    build_default_chapter_renumber_coordinator,
+    default_vector_collection_names,
+)
+
+__all__ = [
+    "ChapterRenumberContext",
+    "ChapterRenumberCoordinator",
+    "ChapterRenumberExtension",
+    "build_default_chapter_renumber_coordinator",
+    "default_vector_collection_names",
+]

application/novel/chapter_renumber/coordinator.py

@@ -0,0 +1,186 @@
+"""删章（并重排章节号）后的扩展编排：伏笔 JSON、快照内嵌 JSON、向量元数据等。
+
+新增一种侧车数据时：实现 ``ChapterRenumberExtension`` 并在依赖注入处注册即可，
+避免在 ``SqliteChapterRepository`` 内无限堆叠硬编码表名。
+"""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Callable, FrozenSet, List, Optional, Protocol, Sequence
+
+from domain.novel.chapter_renumber.json_walk import (
+    DEFAULT_CHAPTER_INTEGER_JSON_KEYS,
+    renumber_chapter_integers_in_json,
+)
+from domain.novel.value_objects.chapter_renumber_spec import ChapterRenumberSpec
+from domain.novel.value_objects.novel_id import NovelId
+from infrastructure.persistence.database.connection import DatabaseConnection
+
+logger = logging.getLogger(__name__)
+
+VectorCollectionResolver = Callable[[str], List[str]]
+
+
+def default_vector_collection_names(novel_id: str) -> List[str]:
+    """默认与各 IndexingService 集合命名一致；迭代时可在 Context 中替换整个 resolver。"""
+    return [
+        f"novel_{novel_id}_chunks",
+        f"novel_{novel_id}_triples",
+        "chapters",
+    ]
+
+
+@dataclass
+class ChapterRenumberContext:
+    """扩展点共享依赖（由 DI 组装，便于单测替换）。"""
+
+    db: DatabaseConnection
+    foreshadowing_repository: Optional[Any] = None
+    vector_store: Optional[Any] = None
+    vector_collection_names_resolver: VectorCollectionResolver = default_vector_collection_names
+    snapshot_json_keys: FrozenSet[str] = field(
+        default_factory=lambda: DEFAULT_CHAPTER_INTEGER_JSON_KEYS
+    )
+
+
+class ChapterRenumberExtension(Protocol):
+    """单种「章号侧车数据」的重排逻辑。"""
+
+    @property
+    def name(self) -> str: ...
+
+    def apply(self, spec: ChapterRenumberSpec, ctx: ChapterRenumberContext) -> None: ...
+
+
+class ForeshadowRegistryChapterRenumberExtension:
+    name = "foreshadow_registry"
+
+    def apply(self, spec: ChapterRenumberSpec, ctx: ChapterRenumberContext) -> None:
+        repo = ctx.foreshadowing_repository
+        if repo is None:
+            return
+        reg = repo.get_by_novel_id(NovelId(spec.novel_id))
+        if reg is None:
+            return
+        reg.apply_chapter_renumber_after_chapter_deleted(spec)
+        repo.save(reg)
+
+
+class VectorStoreChapterRenumberExtension:
+    name = "vector_store"
+
+    def apply(self, spec: ChapterRenumberSpec, ctx: ChapterRenumberContext) -> None:
+        vs = ctx.vector_store
+        if vs is None:
+            return
+        renumber = getattr(vs, "renumber_chapter_metadata_for_novel", None)
+        if not callable(renumber):
+            return
+        names = ctx.vector_collection_names_resolver(spec.novel_id)
+        try:
+            n = int(renumber(spec, names))
+            logger.info(
+                "向量章号元数据已处理 %s 条（含 id 重挂） novel=%s",
+                n,
+                spec.novel_id,
+            )
+        except Exception:
+            logger.exception("向量章号元数据更新失败 novel=%s", spec.novel_id)
+
+
+class SnapshotJsonChapterRenumberExtension:
+    """修正快照中 graph_state / foreshadow_state 内嵌 JSON 的章号整型字段。
+
+    说明：chapter_pointers 存章节主键 id，不随章号重排变化，故不修改。
+    """
+
+    name = "novel_snapshots_json"
+
+    def apply(self, spec: ChapterRenumberSpec, ctx: ChapterRenumberContext) -> None:
+        rows = ctx.db.fetch_all(
+            """
+            SELECT id, graph_state, foreshadow_state
+            FROM novel_snapshots
+            WHERE novel_id = ?
+            """,
+            (spec.novel_id,),
+        )
+        keys = ctx.snapshot_json_keys
+        for row in rows:
+            sid = row["id"]
+            set_parts: List[str] = []
+            params: List[Any] = []
+            for col in ("graph_state", "foreshadow_state"):
+                raw = row.get(col)
+                if not raw or not str(raw).strip():
+                    continue
+                try:
+                    data = json.loads(raw)
+                except json.JSONDecodeError:
+                    logger.warning("快照 %s 列 %s 非 JSON，跳过章号修正", sid, col)
+                    continue
+                new_data = renumber_chapter_integers_in_json(data, spec, keys=keys)
+                new_raw = json.dumps(new_data, ensure_ascii=False)
+                if new_raw == raw:
+                    continue
+                set_parts.append(f"{col} = ?")
+                params.append(new_raw)
+            if not set_parts:
+                continue
+            sql = f"UPDATE novel_snapshots SET {', '.join(set_parts)} WHERE id = ?"
+            params.append(sid)
+            ctx.db.execute(sql, tuple(params))
+        ctx.db.get_connection().commit()
+
+
+class ChapterRenumberCoordinator:
+    """按顺序执行已注册的扩展；单个扩展失败不影响其它扩展（记录日志）。"""
+
+    def __init__(
+        self,
+        context: ChapterRenumberContext,
+        extensions: Sequence[ChapterRenumberExtension],
+    ):
+        self._ctx = context
+        self._extensions = tuple(extensions)
+
+    def on_chapter_deleted(self, novel_id: str, deleted_chapter_number: int) -> None:
+        spec = ChapterRenumberSpec(
+            novel_id=novel_id,
+            deleted_chapter_number=deleted_chapter_number,
+        )
+        for ext in self._extensions:
+            try:
+                ext.apply(spec, self._ctx)
+            except Exception:
+                logger.exception("章号重排扩展失败: %s", ext.name)
+
+
+def build_default_chapter_renumber_coordinator(
+    db: DatabaseConnection,
+    *,
+    foreshadowing_repository: Optional[Any] = None,
+    vector_store: Optional[Any] = None,
+    vector_collection_names_resolver: Optional[VectorCollectionResolver] = None,
+    snapshot_json_keys: Optional[FrozenSet[str]] = None,
+    extra_extensions: Sequence[ChapterRenumberExtension] = (),
+) -> ChapterRenumberCoordinator:
+    """工厂：默认扩展集 + 可选附加扩展（插件入口）。"""
+    ctx = ChapterRenumberContext(
+        db=db,
+        foreshadowing_repository=foreshadowing_repository,
+        vector_store=vector_store,
+        vector_collection_names_resolver=(
+            vector_collection_names_resolver or default_vector_collection_names
+        ),
+        snapshot_json_keys=snapshot_json_keys or DEFAULT_CHAPTER_INTEGER_JSON_KEYS,
+    )
+    extensions: List[ChapterRenumberExtension] = [
+        ForeshadowRegistryChapterRenumberExtension(),
+        VectorStoreChapterRenumberExtension(),
+        SnapshotJsonChapterRenumberExtension(),
+    ]
+    extensions.extend(extra_extensions)
+    return ChapterRenumberCoordinator(ctx, extensions)

domain/novel/chapter_renumber/__init__.py

@@ -0,0 +1,11 @@
+"""章号重排：删章后与关系库一致的引用变换（JSON 遍历、伏笔注册表等）。"""
+
+from domain.novel.chapter_renumber.json_walk import (
+    DEFAULT_CHAPTER_INTEGER_JSON_KEYS,
+    renumber_chapter_integers_in_json,
+)
+
+__all__ = [
+    "DEFAULT_CHAPTER_INTEGER_JSON_KEYS",
+    "renumber_chapter_integers_in_json",
+]

domain/novel/chapter_renumber/json_walk.py

@@ -0,0 +1,47 @@
+"""在任意 JSON 子树中按「键名约定」改写章号整数，避免为每种快照结构写死解析代码。"""
+from __future__ import annotations
+
+from typing import Any, FrozenSet
+
+from domain.novel.value_objects.chapter_renumber_spec import ChapterRenumberSpec
+
+# 默认识别的「整型章号」字段名；新表/新 JSON 只需把键加进集合或通过协调器注入扩展键。
+DEFAULT_CHAPTER_INTEGER_JSON_KEYS: FrozenSet[str] = frozenset(
+    {
+        "chapter_number",
+        "chapter",
+        "planted_in_chapter",
+        "resolved_in_chapter",
+        "suggested_resolve_chapter",
+        "consumed_at_chapter",
+        "first_appearance",
+        "target_chapter_start",
+        "target_chapter_end",
+        "estimated_chapter_start",
+        "estimated_chapter_end",
+        "current_chapter",
+        "last_updated_chapter",
+        "resolve_chapter_window",
+    }
+)
+
+
+def renumber_chapter_integers_in_json(
+    obj: Any,
+    spec: ChapterRenumberSpec,
+    *,
+    keys: FrozenSet[str] = DEFAULT_CHAPTER_INTEGER_JSON_KEYS,
+) -> Any:
+    if isinstance(obj, dict):
+        out = {}
+        for k, v in obj.items():
+            if k in keys and isinstance(v, int) and not isinstance(v, bool):
+                out[k] = spec.shift_chapter_ref(v)
+            else:
+                out[k] = renumber_chapter_integers_in_json(v, spec, keys=keys)
+        return out
+    if isinstance(obj, list):
+        return [renumber_chapter_integers_in_json(x, spec, keys=keys) for x in obj]
+    if isinstance(obj, tuple):
+        return tuple(renumber_chapter_integers_in_json(x, spec, keys=keys) for x in obj)
+    return obj