admin/meijiaka-zy

Fork 0

Files

T

小鱼开发 74983ce5ec feat: init meijiaka-zj project from ai-meijiaka template

2026-04-20 16:39:57 +08:00

21 KiB

Raw Blame History

后端语义治理与架构重构计划

范围：python-api/app/ 全目录
目标：根治需求调整与 Celery→Async Scheduler 迁移导致的命名腐败、语义漂移、类型漂移问题
原则：长期稳定优先，不计短期开发成本
状态：计划中（待团队评审后执行）

一、问题诊断

经过深度代码扫描，当前代码存在六大类语义腐败，按严重程度排序：

P0：调度器核心模型的 `params: dict[str, Any]` 类型漂移

症状：所有 Handler 从裸字典里 params.get("shots")，且因 Redis 序列化反复写 if isinstance(shots, str): shots = json.loads(shots)
风险：这是 Scheduler 取代 Celery 后最脆弱的环节，任何字段名改动都会导致运行时崩溃
关键文件：app/scheduler/models.py, app/scheduler/registry.py, app/scheduler/handlers/video_handler.py

P0：`shot/segment/scene` 的三重命名 + 四处重复定义

症状：ScriptShot（Schema）、ShotData（API）、ShotTask（Service）、ShotUnit（Scheduler）四者并存，字段名 scene/scene_desc、type/shot_type 混用
风险：任何分镜字段改动必须改 4 个类，极易遗漏
关键文件：app/schemas/script.py, app/api/v1/video.py, app/services/kling_video_service.py, app/scheduler/models.py

P0：Kling 供应商语义大规模泄漏到业务层和 API 层

症状：element_id（Kling 主体 ID）、kling_task_id、Omni prompt 语法 <<<element_1>>> 直接出现在 API Schema、Scheduler 模型、数据库模型中
风险：一旦更换视频供应商，影响面会穿透所有层级
关键文件：app/api/v1/video.py, app/api/v1/tasks.py, app/models/avatar.py, app/scheduler/handlers/video_handler.py

P1：`task` / `task_id` 的五重语义混用

症状：FastAPI BackgroundTask、Scheduler Task、Kling API Task、AnyToCopy Task、Volcengine Task 都叫 task
风险：日志堆栈中无法区分层级，调试极其困难
关键文件：app/api/v1/tasks.py, app/scheduler/, app/ai/providers/klingai_provider.py, app/services/

P1：历史残留命名与双轨运行

症状：# 兼容旧字段、video_task_id、image_task_id、cache_err 等 Celery 时代残留；script 任务仍走 BackgroundTask，其他任务走 Scheduler
风险：双轨运行导致统一监控、重试、日志无法覆盖全部任务类型
关键文件：app/scheduler/handlers/video_handler.py, app/scheduler/handlers/image_handler.py, app/api/v1/tasks.py

P2：CRUD 层裸字典更新

症状：avatar_crud.update(db, db_obj=avatar, obj_in={"status": "element_pending"})
风险：拼写错误、状态值非法无法被静态检查捕获
关键文件：app/crud/base.py, app/crud/avatar.py, app/scheduler/handlers/avatar_handler.py

二、架构目标：六层语义治理

我们将整个后端严格划分为 6 个语义层级，每一层只使用属于该层的术语：

┌─────────────────────────────────────────────────────────┐
│  Layer 6: Presentation  (API Schema / 前端适配层)        │
│  术语: Segment, Human, Job, Script, Cover                │
├─────────────────────────────────────────────────────────┤
│  Layer 5: Application   (API 路由 / BackgroundJob)       │
│  术语: Segment, Human, Job, Project                      │
├─────────────────────────────────────────────────────────┤
│  Layer 4: Orchestration (Scheduler / SlotManager)        │
│  术语: Job, JobRecord, Slot, Handler                     │
├─────────────────────────────────────────────────────────┤
│  Layer 3: Domain        (Service / 业务逻辑)             │
│  术语: Segment, Human, VideoComposition, Caption         │
├─────────────────────────────────────────────────────────┤
│  Layer 2: Adapter       (Provider Client / 供应商适配)   │
│  术语: KlingJob, KlingElement, VolcJob, ProviderTaskId   │
├─────────────────────────────────────────────────────────┤
│  Layer 1: Infrastructure (DB / Redis / HTTP / FileSys)  │
│  术语: 仅使用底层技术术语                                │
└─────────────────────────────────────────────────────────┘

核心禁令

element、omni、kling_task_id 等供应商术语禁止出现在 Layer 3 以上
shot 禁止出现在 Layer 3 以上（Kling 术语，业务层统一叫 segment）
task 禁止出现在 Layer 4（Scheduler 内部统一叫 job）
dict[str, Any] 禁止出现在跨层传递的接口中

三、重构阶段（Phase 1-5）

每个 Phase 独立成组，建议按顺序执行。每个 Phase 完成后必须跑通 pytest 和 make lint。

Phase 1：Schema 统一 + 状态机 Enum 化

目标：建立"单一真相源"，消除 shot/segment/scene 的四重定义 预估工时：3-4 天 影响面：全项目基础类型

Task 1.1：新建统一术语 Schema

新建 app/schemas/segment.py

class Segment(BaseModel):
    id: str
    type: Literal["segment", "empty_shot"]
    scene: str                      # 统一为 scene，删除 scene_desc
    voiceover: str
    duration: int | None = None
    human_id: str | None = None     # 业务术语，对应 Kling 的 element_id
    status: SegmentStatus = SegmentStatus.PENDING
    provider_task_id: str | None = None
    video_url: str | None = None
    local_path: str | None = None
    query_fail_count: int = 0

新建 app/schemas/enums.py，定义以下 Enum：
- JobStatus: pending, running, completed, failed
- SegmentStatus: pending, submitted, completed, failed
- AvatarCloneStatus: pending, voice_processing, voice_failed, element_pending, element_processing, element_failed, succeed
- KlingTaskStatus: submitted, processing, succeed, failed（仅限 Provider 层使用）
新建 app/schemas/job.py，定义 JobParams Union：
- VideoJobParams（含 segments: list[Segment]）
- ImageJobParams
- SubtitleJobParams
- CopyJobParams
- AvatarCloneJobParams

Task 1.2：删除重复定义

删除 app/scheduler/models.py 中的 ShotUnit
删除/重构 app/services/kling_video_service.py 中的 ShotTask（字段迁移到 Segment）
删除 app/api/v1/video.py 中的 ShotData，改为引用 Segment
将 app/schemas/script.py 中的 ScriptShot 改为 Segment 的别名或类型适配器

Task 1.3：字段名统一

批量将 scene_desc 重命名为 scene（覆盖 kling_video_service.py, video_handler.py 等）
批量将 shot_type 重命名为 type（在业务层/Schema 层；Provider 层保留 shot_type 仅用于 Kling API 调用）
app/api/v1/tasks.py 中的 shots: list[dict] 改为 segments: list[Segment]

Task 1.4：状态字符串 Enum 化

app/scheduler/models.py 中 TaskRecord.status 类型改为 JobStatus
app/services/kling_video_service.py 中 VideoGenerationJob.status 类型改为 JobStatus
app/models/avatar.py 中 Avatar.status 类型改为 AvatarCloneStatus
app/ai/providers/klingai_provider.py 中所有 Kling 状态字符串操作改为 KlingTaskStatus

验收标准

grep -rn "class ShotUnit\|class ShotTask\|class ShotData\|class ScriptShot" app/ 返回为空（除了注释或别名声明）
grep -rn "scene_desc" app/ | grep -v "__pycache__" 返回为空
mypy app/schemas/ 无类型错误
pytest 通过

Phase 2：Scheduler 层全面"去 task 化"

目标：消除 task 的五重语义混用，建立 Job 专属语义域 预估工时：3-4 天 影响面：app/scheduler/ 目录及引用方

Task 2.1：核心模型与 Registry 重命名

app/scheduler/models.py：TaskRecord → JobRecord
app/scheduler/registry.py：TaskRegistry → JobRegistry
- 所有 task_id 参数/字段 → job_id
- 所有 task_type 参数/字段 → job_type
- running_task_ids → running_job_ids
app/scheduler/engine.py：AsyncEngine 中所有 task → job

Task 2.2：Registry 承担全部序列化职责

在 JobRegistry.get() 中统一完成 JSON 反序列化
- 解析 params 字段时，根据 job_type 路由到正确的 JobParams Pydantic 模型
- 保证 Handler 拿到的 job.params 永远是强类型对象
删除 video_handler.py 和 image_handler.py 中所有的 isinstance(shots, str): json.loads 逻辑
删除 _download_and_upload 中的手动 JSON 类型判断

Task 2.3：`StateChange` 取代裸字典

在 app/scheduler/models.py 中定义：

@dataclass(frozen=True)
class StateChange:
    job_id: str
    field: str
    value: Any

修改 app/scheduler/engine.py：
- _apply_changes(self, changes: list[dict[str, Any]]) → _apply_changes(self, changes: list[StateChange])
- 序列化逻辑移入 StateChange.to_redis_command() 方法
修改 app/scheduler/handlers/base.py：tick() 返回类型改为 list[StateChange]
修改所有 Handler：changes.append({"task_id": ..., "field": ...}) → changes.append(StateChange(job_id=..., field=..., value=...))

Task 2.4：API 层适配

app/api/v1/tasks.py 中：内部变量名 task_id 在引用 Scheduler 时改为 job_id（API URL /tasks/{task_id} 保持不变，仅内部变量和注释调整）
app/api/v1/avatar.py 中：引用 TaskRegistry 的地方改为 JobRegistry

验收标准

grep -rn "TaskRecord\|TaskRegistry\|running_task_ids" app/scheduler/ 返回为空
grep -rn "isinstance(.*shots.*str)" app/scheduler/handlers/ 返回为空
grep -rn '"task_id":' app/scheduler/handlers/ 返回为空（仅 StateChange dataclass 内部可保留）
pytest 通过

Phase 3：建立"供应商防火墙"（Adapter 层隔离）

目标：将 Kling/Volc 术语彻底下压到 Provider 层，业务层以上使用纯业务语义 预估工时：4-5 天 影响面：API Schema、DB 模型、Scheduler 模型、Provider 层

Task 3.1：API 层删除 Kling 术语泄漏

app/api/v1/video.py：
- element_id: int | None = Field(None, description="Kling主体ID") → human_id: int | None = Field(None, description="数字人主体ID")
app/api/v1/tasks.py：
- 同上，所有 element_id → human_id
- VideoParams 中的 shots → segments

Task 3.2：DB 模型增加供应商抽象

app/models/avatar.py：
- element_id: Mapped[int | None] → provider_element_id: Mapped[int | None]
- voice_task_id → provider_voice_job_id
- element_task_id → provider_element_job_id
- 新增 provider: Mapped[str] = mapped_column(default="kling")（为未来多供应商做准备）
生成 Alembic 迁移脚本（字段重命名 + 新增字段）

Task 3.3：Scheduler 模型供应商抽象

app/scheduler/models.py（Phase 2 后的 JobRecord 及 Segment）：
- kling_task_id → provider_task_id
- 如需追溯供应商，增加 provider: str = "kling"

Task 3.4：Provider 返回值模型化

新建 app/ai/providers/kling_dto.py：
- KlingVideoResult
- KlingImageResult
- KlingVoiceResult
- KlingElementResult
修改 app/ai/providers/klingai_provider.py：
- 所有返回裸 dict[str, Any] 的方法改为返回对应的 Kling*Result
- 状态字段类型改为 KlingTaskStatus

Task 3.5：Prompt 语法迁移到 Provider 层

删除 app/scheduler/handlers/video_handler.py 中的：
- _build_omni_prompt()
- _build_empty_shot_video_prompt()

在 app/ai/providers/klingai_provider.py 中新建 KlingPromptBuilder 类：

class KlingPromptBuilder:
    @staticmethod
    def omni_segment(scene: str, voiceover: str, element_id: str | None = None) -> str
    @staticmethod
    def empty_shot(scene: str, voiceover: str) -> str

video_handler.py 调用时只传业务字段（scene, voiceover, human_id），由 Provider 层负责映射为 Kling 语法

Task 3.6：Service 层适配器映射

app/services/kling_video_service.py：
- 删除 avatar_id 废弃字段
- human_id → 在调用 Provider 时映射为 element_id
app/services/qiniu_service.py：
- file_type="avatar" → file_type="clone_video" 或 "human_video"

验收标准

grep -rn "element_id" app/api/ app/schemas/ app/scheduler/models.py | grep -v "provider_element_id" 返回为空
grep -rn "kling_task_id" app/api/ app/schemas/ app/scheduler/models.py 返回为空
grep -rn "<<<element_1>>>\|<<<voice_1>>>" app/scheduler/ app/services/ 返回为空（仅在 Provider 层保留）
Alembic 迁移脚本可正常升级/降级
pytest 通过

Phase 4：清理历史残留 + 消除双轨运行

目标：删除所有 Celery 时代残留，将 script 任务纳入 Scheduler 统一调度 预估工时：2-3 天 影响面：Handler、API 路由、历史命名

Task 4.1：删除兼容旧字段代码

app/scheduler/handlers/video_handler.py：
- 删除 shot["video_task_id"] = kling_task_id # 兼容旧字段
- 删除初始化 shots 时的 "video_task_id": None
app/scheduler/handlers/image_handler.py：
- 删除 params["image_task_id"] = kling_task_id
app/services/kling_video_service.py：
- 删除 avatar_id 字段

Task 4.2：修正历史残留命名

app/core/redis_client.py：删除文档字符串中的 RateLimiter 字样
app/api/v1/tasks.py：
- cache entry → registry entry
- cache_err → registry_err
- Failed to update cache → Failed to update registry
app/core/token_manager.py：_background_tasks → _refresh_tasks
删除 app/services/dto.py

Task 4.3：将 `script` 任务迁移到 Scheduler

新建 app/scheduler/handlers/script_handler.py
- 将 app/api/v1/tasks.py 中 _run_script_task 的逻辑迁移至此
- 继承 AsyncHandler，name = "script"，不占用 Slot（或占用独立 script_slots）
修改 app/api/v1/tasks.py：
- script 任务改为 registry.create(job_type="script", ...)
- 删除 BackgroundTasks 相关参数和 _run_script_task 函数
修改 app/scheduler/main.py：注册 ScriptHandler

验收标准

grep -rn "兼容旧字段\|video_task_id\|image_task_id" app/scheduler/ app/services/ 返回为空
grep -rn "cache_err\|cache entry" app/api/v1/tasks.py 返回为空
app/services/dto.py 不存在
app/api/v1/tasks.py 中无 BackgroundTasks 导入和使用
pytest 通过

Phase 5：CRUD 层强类型化

目标：消灭 CRUD 层的裸字典更新 预估工时：2 天 影响面：CRUD Base、Avatar CRUD、Scheduler Handler

Task 5.1：CRUD Base 类型约束

app/crud/base.py：
- obj_in: dict[str, Any] → obj_in: CreateSchemaType | UpdateSchemaType
- 保留 dict 仅作为 update 的 fallback，但所有业务调用方优先使用 Schema

Task 5.2：Avatar Schema 定义

新建 app/schemas/avatar.py：

class AvatarCreate(BaseModel):
    name: str
    video_url: str
    status: AvatarCloneStatus = AvatarCloneStatus.PENDING

class AvatarUpdate(BaseModel):
    name: str | None = None
    status: AvatarCloneStatus | None = None
    provider_voice_job_id: str | None = None
    provider_element_job_id: str | None = None
    provider_element_id: int | None = None
    fail_reason: str | None = None

app/crud/avatar.py：改为 class CRUDAvatar(CRUDBase[Avatar, AvatarCreate, AvatarUpdate])

Task 5.3：Handler 调用方改造

app/scheduler/handlers/avatar_handler.py：
- 所有 _update_avatar(avatar_id, {"status": "..."}) 改为 _update_avatar(avatar_id, AvatarUpdate(status=AvatarCloneStatus.XXX))
- 删除裸字典辅助函数 _update_avatar 中的 **obj_in 展开，改用 obj_in.model_dump(exclude_unset=True)

验收标准

grep -rn 'obj_in=\{' app/scheduler/handlers/avatar_handler.py 返回为空
mypy app/crud/ 无类型错误
pytest 通过

四、自动化防护网（Phase 5 之后部署）

4.1 预提交钩子：禁词检查

在 .pre-commit-config.yaml 或 Makefile 中增加 lint-semantic：

lint-semantic:
	@echo "Checking semantic boundaries..."
	@! grep -rn "element_id" app/api/ app/schemas/ app/scheduler/models.py | grep -v "provider_element_id" || (echo "ERROR: element_id leaked to upper layers"; exit 1)
	@! grep -rn "kling_task_id" app/api/ app/schemas/ app/scheduler/models.py || (echo "ERROR: kling_task_id leaked to upper layers"; exit 1)
	@! grep -rn "scene_desc" app/ | grep -v "__pycache__" || (echo "ERROR: scene_desc not fully renamed"; exit 1)
	@! grep -rn "TaskRecord\|TaskRegistry\|running_task_ids" app/scheduler/ || (echo "ERROR: Scheduler task naming not fully migrated"; exit 1)
	@! grep -rn "<<<element_1>>>\|<<<voice_1>>>" app/scheduler/ app/services/ || (echo "ERROR: Kling prompt syntax leaked"; exit 1)
	@echo "Semantic check passed"

4.2 mypy 渐进严格化

在 pyproject.toml 中为 app/scheduler/ 和 app/schemas/ 单独开启 strict = true
逐步扩展至 app/api/ 和 app/services/

4.3 AGENTS.md 术语表（Glossary）

在 AGENTS.md 中新增"统一术语表"章节（见下文），所有 AI Agent 修改代码前必须查阅。

五、风险与回滚策略

风险	影响	mitigation
Phase 1 删除 `ScriptShot` 影响前端类型生成	中	`ScriptShot` 保留为 `Segment` 的 `TypeAlias` 一个 Sprint，待前端适配后删除
Phase 2 `JobRegistry` 重命名导致 API 层引用遗漏	高	使用 IDE 全局重构（PyCharm/Ruff/Rename Symbol），执行后跑全量 `pytest`
Phase 3 DB 字段重命名需要数据迁移	中	Alembic 脚本必须包含 `op.alter_column` 的 `existing_type` 和 `existing_nullable`
Phase 4 `script` 迁出 BackgroundTask 后响应时间变长	低	脚本生成仍立即返回 `job_id`，前端通过轮询 `/tasks/{job_id}` 获取结果，接口契约不变
多 Phase 并行开发导致冲突	高	严禁并行：必须按 1→2→3→4→5 顺序执行，每个 Phase 合并到主分支后再开始下一个

六、作为 GitHub Project Task List 的格式

若导入 GitHub Project，建议按以下结构建 5 个 Milestone：

### Milestone 1: Schema Unification
- [ ] #101 Create `app/schemas/segment.py` with `Segment` model
- [ ] #102 Create `app/schemas/enums.py` with `JobStatus`, `SegmentStatus`, `AvatarCloneStatus`, `KlingTaskStatus`
- [ ] #103 Create `app/schemas/job.py` with `JobParams` Union
- [ ] #104 Remove `ShotUnit` from `app/scheduler/models.py`
- [ ] #105 Remove `ShotTask` from `app/services/kling_video_service.py`
- [ ] #106 Remove `ShotData` from `app/api/v1/video.py`
- [ ] #107 Rename `scene_desc` → `scene` across codebase
- [ ] #108 Migrate all `status` strings to Enums

### Milestone 2: Scheduler De-tasking
- [ ] #201 Rename `TaskRecord` → `JobRecord`
- [ ] #202 Rename `TaskRegistry` → `JobRegistry`
- [ ] #203 Registry auto-deserializes `JobParams` models
- [ ] #204 Replace `dict` changes with `StateChange` dataclass
- [ ] #205 Update all Handlers to return `list[StateChange]`

### Milestone 3: Vendor Firewall
- [ ] #301 API layer: `element_id` → `human_id`
- [ ] #302 DB model: add `provider` field, rename task/element IDs
- [ ] #303 Scheduler model: `kling_task_id` → `provider_task_id`
- [ ] #304 Provider DTOs: `KlingVideoResult`, `KlingImageResult`, etc.
- [ ] #305 Move `KlingPromptBuilder` to Provider layer
- [ ] #306 Alembic migration for avatar table changes

### Milestone 4: Cleanup & Unification
- [ ] #401 Remove legacy compatibility fields (`video_task_id`, `image_task_id`)
- [ ] #402 Fix historical naming (`cache_err`, `RateLimiter` docstrings, etc.)
- [ ] #403 Delete `app/services/dto.py`
- [ ] #404 Migrate `script` task from BackgroundTask to Scheduler

### Milestone 5: CRUD Strong Typing
- [ ] #501 Create `AvatarCreate` / `AvatarUpdate` schemas
- [ ] #502 Type-constrain CRUDBase
- [ ] #503 Refactor `avatar_handler.py` to use `AvatarUpdate` instead of raw dicts
- [ ] #504 Add `lint-semantic` to Makefile / pre-commit
- [ ] #505 Update `AGENTS.md` with Glossary and layer rules

21 KiB Raw Blame History Unescape Escape

后端语义治理与架构重构计划

一、问题诊断

P0：调度器核心模型的 params: dict[str, Any] 类型漂移

P0：shot/segment/scene 的三重命名 + 四处重复定义

P0：Kling 供应商语义大规模泄漏到业务层和 API 层

P1：task / task_id 的五重语义混用

P1：历史残留命名与双轨运行

P2：CRUD 层裸字典更新

二、架构目标：六层语义治理

核心禁令

三、重构阶段（Phase 1-5）

Phase 1：Schema 统一 + 状态机 Enum 化

Task 1.1：新建统一术语 Schema

Task 1.2：删除重复定义

Task 1.3：字段名统一

Task 1.4：状态字符串 Enum 化

验收标准

Phase 2：Scheduler 层全面"去 task 化"

Task 2.1：核心模型与 Registry 重命名

Task 2.2：Registry 承担全部序列化职责

Task 2.3：StateChange 取代裸字典

Task 2.4：API 层适配

验收标准

Phase 3：建立"供应商防火墙"（Adapter 层隔离）

Task 3.1：API 层删除 Kling 术语泄漏

Task 3.2：DB 模型增加供应商抽象

Task 3.3：Scheduler 模型供应商抽象

Task 3.4：Provider 返回值模型化

Task 3.5：Prompt 语法迁移到 Provider 层

Task 3.6：Service 层适配器映射

验收标准

Phase 4：清理历史残留 + 消除双轨运行

Task 4.1：删除兼容旧字段代码

Task 4.2：修正历史残留命名

Task 4.3：将 script 任务迁移到 Scheduler

验收标准

Phase 5：CRUD 层强类型化

Task 5.1：CRUD Base 类型约束

Task 5.2：Avatar Schema 定义

Task 5.3：Handler 调用方改造

验收标准

四、自动化防护网（Phase 5 之后部署）

4.1 预提交钩子：禁词检查

4.2 mypy 渐进严格化

4.3 AGENTS.md 术语表（Glossary）

五、风险与回滚策略

六、作为 GitHub Project Task List 的格式

七、相关文档

21 KiB

Raw Blame History

P0：调度器核心模型的 `params: dict[str, Any]` 类型漂移

P0：`shot/segment/scene` 的三重命名 + 四处重复定义

P1：`task` / `task_id` 的五重语义混用

Task 2.3：`StateChange` 取代裸字典

Task 4.3：将 `script` 任务迁移到 Scheduler