feat: M3 — 伏笔账本 + 节奏引擎 + 大纲（含并发记账 bugfix）
- 伏笔账本：纯函数状态机(OPEN/PARTIAL/CLOSED/OVERDUE) + ForeshadowLedger repo；验收后到期扫描(BackgroundTask 自建 session 置 OVERDUE)；登记/状态变更端点 - 节奏 + 三审齐：foreshadow-analyst + pace-checker 并入 LangGraph 并行审(REVIEW_SPECS)，collect 分列落 chapter_reviews(conflicts/foreshadow_sug/pace)，review SSE 加 foreshadow/pace 事件 - 大纲：outliner Agent 产 OutlineResult(含 foreshadow_windows)，POST /outline 逐章 upsert outline 表；GET /foreshadow?status= 看板 - 前端：伏笔四泳道看板(OVERDUE 琥珀) + 大纲编辑器(窗口徽标) + 节奏节拍图(▁▃▅) + 审稿页消费 foreshadow/pace SSE - bugfix(T3.8)：并行三审共用请求 session 记账触发 'Session is already flushing' → foreshadow/pace 静默丢失；SqlAlchemyLedgerSink.record 改 add-only(靠端点/事务 commit)，加并发回归测试 - M3 E2E：真实 DB + mock 网关零 token 走通 埋设→进展→验收后扫描 OVERDUE→看板 + 大纲含窗口 + 三审齐 SSE/留痕；E2E 暴露并钉住上述 bug - 门禁绿：mypy 111 / pytest 228(0 xfailed) / alembic 无漂移；前端 gen:api/lint/tsc/vitest 69/build
This commit is contained in:
Yaojia Wang
159
apps/api/ww_api/routers/foreshadow.py
Normal file
159
apps/api/ww_api/routers/foreshadow.py
Normal file
@@ -0,0 +1,159 @@
|
||||
"""伏笔登记 / 状态变更端点（C3 扩 / ARCH §6.2, §7.2；不变量 #3）。
|
||||
|
||||
- POST /projects/:id/foreshadow 作者显式登记一条伏笔（status=OPEN）。
|
||||
- PATCH /projects/:id/foreshadow/:code 状态机转移 和/或 追加进展。
|
||||
|
||||
登记/改状态是**作者显式动作**（不变量 #3：伏笔入库不经 AI 静默写库；验收后到期扫描
|
||||
是确定性纯函数置位，见 `services/foreshadow_scan.py`）。
|
||||
|
||||
提交边界：`ForeshadowLedgerRepo` 写方法只 `flush()`，端点写后 `await session.commit()`。
|
||||
|
||||
**T3.5 续接点**：本 router 是 foreshadow 端点的归属处。T3.5 的看板查询
|
||||
`GET /projects/:id/foreshadow?status=` 直接加到本 router（调 `repo.list_by_status`）；
|
||||
大纲 `POST /projects/:id/outline` 与伏笔无关，建议落独立 `routers/outline.py`
|
||||
（或 projects router），不混进本文件。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from typing import Annotated
|
||||
|
||||
from fastapi import APIRouter, Depends, Request
|
||||
from sqlalchemy.exc import IntegrityError
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from ww_core.domain import ForeshadowLedgerRepo, ForeshadowLedgerView
|
||||
from ww_core.domain.foreshadow_state import ForeshadowStatus, InvalidTransition
|
||||
from ww_db import get_session
|
||||
from ww_shared import AppError, ErrorCode
|
||||
|
||||
from ww_api.logging_config import get_logger
|
||||
from ww_api.schemas.foreshadow import (
|
||||
ForeshadowBoardResponse,
|
||||
ForeshadowRegisterRequest,
|
||||
ForeshadowTransitionRequest,
|
||||
ForeshadowView,
|
||||
)
|
||||
from ww_api.services.project_deps import get_foreshadow_repo
|
||||
|
||||
log = get_logger("ww.api.foreshadow")
|
||||
|
||||
router = APIRouter(prefix="/projects", tags=["foreshadow"])
|
||||
|
||||
ForeshadowRepoDep = Annotated[ForeshadowLedgerRepo, Depends(get_foreshadow_repo)]
|
||||
SessionDep = Annotated[AsyncSession, Depends(get_session)]
|
||||
|
||||
|
||||
def _to_view(v: ForeshadowLedgerView) -> ForeshadowView:
|
||||
# ForeshadowLedgerView 与 ForeshadowView 字段同名，逐字段映射（snake_case 契约）。
|
||||
return ForeshadowView.model_validate(v, from_attributes=True)
|
||||
|
||||
|
||||
@router.post("/{project_id}/foreshadow", status_code=201)
|
||||
async def register_foreshadow(
|
||||
project_id: uuid.UUID,
|
||||
body: ForeshadowRegisterRequest,
|
||||
request: Request,
|
||||
repo: ForeshadowRepoDep,
|
||||
session: SessionDep,
|
||||
) -> ForeshadowView:
|
||||
"""登记一条伏笔（status=OPEN）。重复 `code` → DB 唯一约束冲突 → VALIDATION 信封。"""
|
||||
request_id = getattr(request.state, "request_id", None)
|
||||
try:
|
||||
view = await repo.register(
|
||||
project_id,
|
||||
code=body.code,
|
||||
title=body.title,
|
||||
planted_at=body.planted_at,
|
||||
content=body.content,
|
||||
expected_close_from=body.expected_close_from,
|
||||
expected_close_to=body.expected_close_to,
|
||||
importance=body.importance,
|
||||
)
|
||||
await session.commit()
|
||||
except IntegrityError as exc:
|
||||
# `(project_id, code)` 唯一约束冲突（register 仅 INSERT、不 upsert，见 foreshadow_repo）。
|
||||
await session.rollback()
|
||||
raise AppError(
|
||||
ErrorCode.VALIDATION,
|
||||
f"伏笔代号已存在：{body.code}",
|
||||
{"field": "code", "code": body.code, "reason": "duplicate"},
|
||||
) from exc
|
||||
log.info(
|
||||
"foreshadow_registered",
|
||||
project_id=str(project_id),
|
||||
request_id=request_id,
|
||||
code=body.code,
|
||||
)
|
||||
return _to_view(view)
|
||||
|
||||
|
||||
@router.get("/{project_id}/foreshadow")
|
||||
async def list_foreshadow(
|
||||
project_id: uuid.UUID,
|
||||
repo: ForeshadowRepoDep,
|
||||
status: str | None = None,
|
||||
) -> ForeshadowBoardResponse:
|
||||
"""伏笔看板：按 `status` 过滤（缺省=全部），按 code 升序。
|
||||
|
||||
`status` 非法（不在 OPEN/PARTIAL/CLOSED/OVERDUE）→ VALIDATION 信封。四泳道前端
|
||||
据 `status` 分组；OVERDUE 泳道 + 逾期标记用 `expected_close_to`（看板字段已齐）。
|
||||
"""
|
||||
if status is not None and status not in {s.value for s in ForeshadowStatus}:
|
||||
raise AppError(
|
||||
ErrorCode.VALIDATION,
|
||||
f"非法状态过滤：{status}",
|
||||
{"field": "status", "reason": "invalid_status"},
|
||||
)
|
||||
views = await repo.list_by_status(project_id, status)
|
||||
return ForeshadowBoardResponse(foreshadow=[_to_view(v) for v in views])
|
||||
|
||||
|
||||
@router.patch("/{project_id}/foreshadow/{code}")
|
||||
async def update_foreshadow(
|
||||
project_id: uuid.UUID,
|
||||
code: str,
|
||||
body: ForeshadowTransitionRequest,
|
||||
request: Request,
|
||||
repo: ForeshadowRepoDep,
|
||||
session: SessionDep,
|
||||
) -> ForeshadowView:
|
||||
"""状态机转移 和/或 追加进展。非法转移 → VALIDATION 信封；不存在 → NOT_FOUND。
|
||||
|
||||
`to_status` 与 `progress_entry` 皆可选；两者都缺 → VALIDATION（无操作）。先转移、后追加。
|
||||
"""
|
||||
request_id = getattr(request.state, "request_id", None)
|
||||
if body.to_status is None and body.progress_entry is None:
|
||||
raise AppError(
|
||||
ErrorCode.VALIDATION,
|
||||
"至少提供 `to_status` 或 `progress_entry` 之一",
|
||||
{"reason": "empty_update"},
|
||||
)
|
||||
|
||||
view: ForeshadowLedgerView
|
||||
try:
|
||||
if body.to_status is not None:
|
||||
view = await repo.transition(project_id, code, to_status=body.to_status)
|
||||
if body.progress_entry is not None:
|
||||
view = await repo.record_progress(project_id, code, entry=body.progress_entry)
|
||||
await session.commit()
|
||||
except InvalidTransition as exc:
|
||||
await session.rollback()
|
||||
raise AppError(
|
||||
ErrorCode.VALIDATION,
|
||||
str(exc),
|
||||
{"field": "to_status", "code": code, "reason": "invalid_transition"},
|
||||
) from exc
|
||||
except LookupError as exc:
|
||||
await session.rollback()
|
||||
raise AppError(ErrorCode.NOT_FOUND, f"foreshadow not found: {code}") from exc
|
||||
|
||||
log.info(
|
||||
"foreshadow_updated",
|
||||
project_id=str(project_id),
|
||||
request_id=request_id,
|
||||
code=code,
|
||||
to_status=body.to_status,
|
||||
has_progress=body.progress_entry is not None,
|
||||
)
|
||||
return _to_view(view)
|
||||
135
apps/api/ww_api/routers/outline.py
Normal file
135
apps/api/ww_api/routers/outline.py
Normal file
@@ -0,0 +1,135 @@
|
||||
"""大纲生成端点（C3 扩 / ARCH §5.4 outliner / §7.2 POST /outline；不变量 #2/#3）。
|
||||
|
||||
POST /projects/:id/outline：作者显式发起大纲生成 + 持久化。
|
||||
|
||||
流程：组确定性上下文（设定 + 已登记伏笔 + 人物 + 世界观）→ `run_outline`（analyst 网关，
|
||||
结构化 `OutlineResult`）→ 逐章 upsert `outline` 表 → 端点末尾一次 `commit()`。
|
||||
|
||||
提交边界：网关 ledger 只 flush（run_outline 产 1 条 usage）、`OutlineWriteRepo.upsert_chapter`
|
||||
只 flush → 端点末尾 `await session.commit()`（否则 usage_ledger + outline 行静默丢失，见 gotcha）。
|
||||
|
||||
不变量 #2：经 `build_gateway_for_tier(..., "analyst")` 注入；outliner_spec 只声明档位不传 model。
|
||||
不变量 #3：outliner `writes=["outline"]` 经此**作者发起**端点落地，非 AI 静默写其它表；
|
||||
run_outline 节点本身只读不写库。无凭据 → `LLM_UNAVAILABLE`（友好提示，仿 draft/review）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from typing import Annotated
|
||||
|
||||
from fastapi import APIRouter, Depends, Request
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from ww_agents import outliner_spec
|
||||
from ww_core.domain import ForeshadowLedgerRepo, OutlineWriteRepo, ProjectRepo
|
||||
from ww_core.domain.repositories import MemoryRepos
|
||||
from ww_core.orchestrator import run_outline
|
||||
from ww_db import get_session
|
||||
from ww_llm_gateway import Gateway
|
||||
from ww_shared import AppError, ErrorCode
|
||||
|
||||
from ww_api.logging_config import get_logger
|
||||
from ww_api.schemas.outline import (
|
||||
ForeshadowWindowView,
|
||||
OutlineChapterView,
|
||||
OutlineGenerateRequest,
|
||||
OutlineResponse,
|
||||
)
|
||||
from ww_api.services.credentials import STUB_OWNER_ID
|
||||
from ww_api.services.outline_context import build_outline_context
|
||||
from ww_api.services.project_deps import (
|
||||
get_foreshadow_repo,
|
||||
get_memory_repos,
|
||||
get_outline_gateway,
|
||||
get_outline_write_repo,
|
||||
get_project_repo,
|
||||
)
|
||||
|
||||
log = get_logger("ww.api.outline")
|
||||
|
||||
router = APIRouter(prefix="/projects", tags=["outline"])
|
||||
|
||||
ProjectRepoDep = Annotated[ProjectRepo, Depends(get_project_repo)]
|
||||
ForeshadowRepoDep = Annotated[ForeshadowLedgerRepo, Depends(get_foreshadow_repo)]
|
||||
MemoryReposDep = Annotated[MemoryRepos, Depends(get_memory_repos)]
|
||||
OutlineWriteRepoDep = Annotated[OutlineWriteRepo, Depends(get_outline_write_repo)]
|
||||
OutlineGatewayDep = Annotated[Gateway, Depends(get_outline_gateway)]
|
||||
SessionDep = Annotated[AsyncSession, Depends(get_session)]
|
||||
|
||||
|
||||
@router.post("/{project_id}/outline")
|
||||
async def generate_outline(
|
||||
project_id: uuid.UUID,
|
||||
body: OutlineGenerateRequest,
|
||||
request: Request,
|
||||
project_repo: ProjectRepoDep,
|
||||
foreshadow_repo: ForeshadowRepoDep,
|
||||
memory_repos: MemoryReposDep,
|
||||
outline_repo: OutlineWriteRepoDep,
|
||||
gateway: OutlineGatewayDep,
|
||||
session: SessionDep,
|
||||
) -> OutlineResponse:
|
||||
"""生成大纲并逐章持久化。无凭据 → LLM_UNAVAILABLE；项目不存在 → NOT_FOUND。"""
|
||||
request_id = getattr(request.state, "request_id", None)
|
||||
|
||||
project = await project_repo.get(STUB_OWNER_ID, project_id)
|
||||
if project is None:
|
||||
raise AppError(ErrorCode.NOT_FOUND, f"project not found: {project_id}")
|
||||
|
||||
foreshadow = await foreshadow_repo.list_by_status(project_id, None)
|
||||
characters = await memory_repos.character.list_for_project(project_id)
|
||||
world_entities = await memory_repos.world_entity.list_for_project(project_id)
|
||||
context = build_outline_context(
|
||||
project=project,
|
||||
foreshadow=foreshadow,
|
||||
characters=characters,
|
||||
world_entities=world_entities,
|
||||
)
|
||||
|
||||
log.info(
|
||||
"outline_generate_start",
|
||||
project_id=str(project_id),
|
||||
request_id=request_id,
|
||||
volume=body.volume,
|
||||
context_len=len(context),
|
||||
foreshadow_count=len(foreshadow),
|
||||
)
|
||||
|
||||
# run_outline 产结构化大纲（analyst 网关；网关失败上抛，无凭据 → LLM_UNAVAILABLE）。
|
||||
result = await run_outline(
|
||||
outliner_spec,
|
||||
context=context,
|
||||
gateway=gateway,
|
||||
user_id=STUB_OWNER_ID,
|
||||
project_id=project_id,
|
||||
)
|
||||
|
||||
chapters: list[OutlineChapterView] = []
|
||||
for chapter in result.chapters:
|
||||
windows = [w.model_dump() for w in chapter.foreshadow_windows]
|
||||
await outline_repo.upsert_chapter(
|
||||
project_id,
|
||||
volume=body.volume,
|
||||
chapter_no=chapter.no,
|
||||
beats=chapter.beats,
|
||||
foreshadow_windows=windows,
|
||||
)
|
||||
chapters.append(
|
||||
OutlineChapterView(
|
||||
no=chapter.no,
|
||||
volume=body.volume,
|
||||
beats=list(chapter.beats),
|
||||
foreshadow_windows=[ForeshadowWindowView(**w) for w in windows],
|
||||
)
|
||||
)
|
||||
|
||||
# 提交边界：网关 ledger + outline upsert 均只 flush → 端点末尾一次 commit。
|
||||
await session.commit()
|
||||
|
||||
log.info(
|
||||
"outline_generate_done",
|
||||
project_id=str(project_id),
|
||||
request_id=request_id,
|
||||
chapter_count=len(chapters),
|
||||
)
|
||||
return OutlineResponse(chapters=chapters)
|
||||
@@ -17,7 +17,7 @@ import uuid
|
||||
from collections.abc import AsyncIterator
|
||||
from typing import Annotated
|
||||
|
||||
from fastapi import APIRouter, Depends, Request
|
||||
from fastapi import APIRouter, BackgroundTasks, Depends, Request
|
||||
from fastapi.responses import StreamingResponse
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from ww_core.domain.chapter_repo import ChapterRepo
|
||||
@@ -59,6 +59,7 @@ from ww_api.services.accept_service import (
|
||||
)
|
||||
from ww_api.services.credentials import STUB_OWNER_ID
|
||||
from ww_api.services.digest_extraction import extract_digest_facts
|
||||
from ww_api.services.foreshadow_scan import SessionFactory, run_overdue_scan
|
||||
from ww_api.services.project_deps import (
|
||||
get_chapter_repo,
|
||||
get_digest_append_repo,
|
||||
@@ -67,6 +68,7 @@ from ww_api.services.project_deps import (
|
||||
get_project_repo,
|
||||
get_review_gateway,
|
||||
get_review_repo,
|
||||
get_session_factory,
|
||||
get_writer_gateway,
|
||||
)
|
||||
|
||||
@@ -302,14 +304,23 @@ async def accept_chapter(
|
||||
chapter_no: int,
|
||||
body: AcceptRequest,
|
||||
request: Request,
|
||||
background_tasks: BackgroundTasks,
|
||||
chapter_repo: ChapterRepoDep,
|
||||
digest_repo: DigestRepoDep,
|
||||
review_repo: ReviewRepoDep,
|
||||
gateway: DigestGatewayDep,
|
||||
session: Annotated[AsyncSession, Depends(get_session)],
|
||||
session_factory: Annotated[SessionFactory, Depends(get_session_factory)],
|
||||
) -> AcceptResponse:
|
||||
"""验收事务 + 冲突 gate（§5.5）：gate（事务前）→ 终稿提炼 digest（事务外，R2）→
|
||||
单原子事务（晋升 + digest + 裁决留痕）→ 一次 commit。
|
||||
单原子事务（晋升 + digest + 裁决留痕）→ 一次 commit → 登记**验收后伏笔到期扫描**
|
||||
BackgroundTask（M3-b/d，§6.2）。
|
||||
|
||||
到期扫描接 §5.5 步骤 3 的 `TODO(M3)` 占位：验收提交成功**后**，把
|
||||
`current_ch > expected_close_to AND status≠CLOSED` 的伏笔确定性置 OVERDUE。
|
||||
伏笔登记/回收（PARTIAL/CLOSED）的「采纳建议」经作者经 foreshadow 端点显式确认，
|
||||
不在验收事务里 AI 静默改库（不变量 #3）。**§7.4 持久性局限**：BackgroundTask 进程内
|
||||
跑、重启丢失——原型可接受（见 `services/foreshadow_scan.py`，不引入 jobs 表）。
|
||||
"""
|
||||
request_id = getattr(request.state, "request_id", None)
|
||||
# R3：审稿真相从领域表重读（最近一条 chapter_reviews），不依赖 checkpoint。
|
||||
@@ -350,6 +361,17 @@ async def accept_chapter(
|
||||
latest_review=latest_review,
|
||||
decisions=body.decisions,
|
||||
)
|
||||
|
||||
# 验收**提交成功后**登记伏笔到期扫描 BackgroundTask（M3-b/d）。current_chapter=刚验收章号；
|
||||
# 任务在请求 session 关闭后跑，故 run_overdue_scan 自建新 session 并 commit（§7.4 局限可接受）。
|
||||
background_tasks.add_task(
|
||||
run_overdue_scan,
|
||||
session_factory,
|
||||
project_id=project_id,
|
||||
chapter_no=chapter_no,
|
||||
request_id=request_id,
|
||||
)
|
||||
|
||||
return AcceptResponse(
|
||||
project_id=project_id,
|
||||
chapter_no=chapter_no,
|
||||
|
||||
Reference in New Issue
Block a user