feat(composite): M7.2b 因子组合落库 + /api/composites CRUD
- factor_composite 表（migration c3e9a0d1f4b5，MySQL 已应用；name 唯一） - CompositeDefinition/Component 实体 + CompositeRepository Protocol + SQLAlchemy 实现 - /api/composites：POST（注册表自动填充组件 direction；未注册因子 400）、GET 列表/详情、DELETE - tests/test_composites_api.py（repo CRUD/同名拒绝/删除、API 方向填充/404/400）；全量 pytest 通过
This commit is contained in:
Simon
@@ -0,0 +1,69 @@
|
||||
"""因子组合 API（M7.2b）：/api/composites CRUD。
|
||||
|
||||
组合 = 可复用因子权重集；计算时方向取因子注册表，落库冗余快照。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from fastapi import APIRouter, HTTPException
|
||||
|
||||
from app.api.deps import CompositeRepoDep, DbSession
|
||||
from app.application.services.job_executor import new_id
|
||||
from app.domain.entities.composite import CompositeComponent, CompositeDefinition
|
||||
from app.quant.factors import FactorError, get_factor
|
||||
|
||||
router = APIRouter(prefix="/composites", tags=["composites"])
|
||||
|
||||
|
||||
def _fill_direction(definition: CompositeDefinition) -> CompositeDefinition:
|
||||
"""以因子注册表元数据补齐/校正组件 direction（登记但不可计算的因子报错）。"""
|
||||
out = []
|
||||
for c in definition.components:
|
||||
try:
|
||||
defn, _fn = get_factor(c.name)
|
||||
except FactorError as exc:
|
||||
raise HTTPException(status_code=400, detail=str(exc)) from exc
|
||||
out.append(CompositeComponent(name=c.name, weight=c.weight, direction=defn.direction))
|
||||
return definition.model_copy(update={"components": out})
|
||||
|
||||
|
||||
@router.post("", summary="保存因子组合", response_model=CompositeDefinition)
|
||||
def create_composite(
|
||||
definition: CompositeDefinition,
|
||||
composite_repo: CompositeRepoDep,
|
||||
session: DbSession,
|
||||
) -> CompositeDefinition:
|
||||
prepared = _fill_direction(definition.model_copy(update={"id": ""}))
|
||||
try:
|
||||
saved = composite_repo.save(
|
||||
prepared.model_copy(update={"id": new_id("CF")})
|
||||
)
|
||||
session.commit()
|
||||
return saved
|
||||
except ValueError as exc:
|
||||
raise HTTPException(status_code=400, detail=str(exc)) from exc
|
||||
|
||||
|
||||
@router.get("", summary="因子组合列表", response_model=list[CompositeDefinition])
|
||||
def list_composites(composite_repo: CompositeRepoDep) -> list[CompositeDefinition]:
|
||||
return composite_repo.list()
|
||||
|
||||
|
||||
@router.get("/{composite_id}", summary="读取因子组合", response_model=CompositeDefinition)
|
||||
def get_composite(composite_id: str, composite_repo: CompositeRepoDep) -> CompositeDefinition:
|
||||
row = composite_repo.get(composite_id)
|
||||
if row is None:
|
||||
raise HTTPException(status_code=404, detail=f"组合 {composite_id} 不存在")
|
||||
return row
|
||||
|
||||
|
||||
@router.delete("/{composite_id}", summary="删除因子组合")
|
||||
def delete_composite(
|
||||
composite_id: str,
|
||||
composite_repo: CompositeRepoDep,
|
||||
session: DbSession,
|
||||
) -> dict:
|
||||
if not composite_repo.delete(composite_id):
|
||||
raise HTTPException(status_code=404, detail=f"组合 {composite_id} 不存在")
|
||||
session.commit()
|
||||
return {"deleted": composite_id}
|
||||
@@ -11,6 +11,7 @@ from fastapi import Depends
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.application.services.selection_service import SelectionService
|
||||
from app.domain.repositories.composite import CompositeRepository
|
||||
from app.domain.repositories.factor import FactorRepository
|
||||
from app.domain.repositories.jobs import ExperimentRepository, JobRepository
|
||||
from app.domain.repositories.market import (
|
||||
@@ -19,6 +20,9 @@ from app.domain.repositories.market import (
|
||||
StockRepository,
|
||||
)
|
||||
from app.domain.repositories.selection import SelectionRepository
|
||||
from app.infrastructure.persistence.sqlalchemy.repositories.composite_impl import (
|
||||
SqlAlchemyCompositeRepository,
|
||||
)
|
||||
from app.infrastructure.persistence.sqlalchemy.repositories.factor_impl import (
|
||||
SqlAlchemyFactorRepository,
|
||||
)
|
||||
@@ -78,6 +82,10 @@ def _factor_repo_factory(session: DbSession) -> FactorRepository:
|
||||
return SqlAlchemyFactorRepository(session)
|
||||
|
||||
|
||||
def _composite_repo_factory(session: DbSession) -> CompositeRepository:
|
||||
return SqlAlchemyCompositeRepository(session)
|
||||
|
||||
|
||||
StockRepoDep = Annotated[StockRepository, Depends(_stock_repo_factory)]
|
||||
DailyRepoDep = Annotated[DailyBarRepository, Depends(_daily_repo_factory)]
|
||||
EngineDep = Annotated[QuantEngine, Depends(_engine_factory)]
|
||||
@@ -85,6 +93,7 @@ ResearchServiceDep = Annotated[ResearchService, Depends(_service_factory)]
|
||||
SelectionServiceDep = Annotated[SelectionService, Depends(_selection_service_factory)]
|
||||
SelectionRepoDep = Annotated[SelectionRepository, Depends(_selection_repo_factory)]
|
||||
FactorRepoDep = Annotated[FactorRepository, Depends(_factor_repo_factory)]
|
||||
CompositeRepoDep = Annotated[CompositeRepository, Depends(_composite_repo_factory)]
|
||||
|
||||
|
||||
def _job_repo_factory(session: DbSession):
|
||||
|
||||
@@ -8,12 +8,23 @@ from __future__ import annotations
|
||||
|
||||
from fastapi import APIRouter
|
||||
|
||||
from app.api import agent, experiments, factors, health, jobs, research, selections, stocks
|
||||
from app.api import (
|
||||
agent,
|
||||
composites,
|
||||
experiments,
|
||||
factors,
|
||||
health,
|
||||
jobs,
|
||||
research,
|
||||
selections,
|
||||
stocks,
|
||||
)
|
||||
|
||||
api_router = APIRouter()
|
||||
api_router.include_router(health.router)
|
||||
api_router.include_router(stocks.router)
|
||||
api_router.include_router(factors.router)
|
||||
api_router.include_router(composites.router)
|
||||
api_router.include_router(research.router)
|
||||
api_router.include_router(selections.router)
|
||||
api_router.include_router(jobs.router)
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
"""因子组合（Composite Factor）领域实体（M7.2b，v2 §13）。
|
||||
|
||||
组合 = 一组 {因子, 权重} + method（MVP fixed：截面 zscore×方向×权重求和；
|
||||
方向在计算时取因子注册表元数据，落库时冗余快照以便列表展示）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import datetime
|
||||
|
||||
from pydantic import BaseModel, Field, model_validator
|
||||
|
||||
|
||||
class CompositeComponent(BaseModel):
|
||||
name: str
|
||||
weight: float = Field(default=1.0, gt=0)
|
||||
direction: str = Field(default="higher_is_better")
|
||||
|
||||
|
||||
class CompositeDefinition(BaseModel):
|
||||
id: str = ""
|
||||
name: str = Field(min_length=1, max_length=64)
|
||||
method: str = Field(default="fixed", pattern="^(fixed)$")
|
||||
description: str = ""
|
||||
components: list[CompositeComponent] = Field(min_length=1)
|
||||
created_at: datetime | None = None
|
||||
|
||||
@model_validator(mode="after")
|
||||
def _no_duplicate(self) -> CompositeDefinition:
|
||||
names = [c.name for c in self.components]
|
||||
if len(set(names)) != len(names):
|
||||
raise ValueError("components 存在重复因子名")
|
||||
return self
|
||||
@@ -0,0 +1,19 @@
|
||||
"""Composite Factor Repository Protocol（M7.2b）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Protocol
|
||||
|
||||
from app.domain.entities.composite import CompositeDefinition
|
||||
|
||||
|
||||
class CompositeRepository(Protocol):
|
||||
def save(self, definition: CompositeDefinition) -> CompositeDefinition:
|
||||
"""新建组合（name 冲突抛 ValueError）。"""
|
||||
|
||||
def get(self, composite_id: str) -> CompositeDefinition | None: ...
|
||||
|
||||
def list(self) -> list[CompositeDefinition]: ...
|
||||
|
||||
def delete(self, composite_id: str) -> bool:
|
||||
"""删除；不存在返回 False。"""
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
"""factor_composite 表（M7.2b 因子组合保存/复用）
|
||||
|
||||
Revision ID: c3e9a0d1f4b5
|
||||
Revises: b7f2a5e81c33
|
||||
Create Date: 2026-09-09
|
||||
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Sequence
|
||||
|
||||
import sqlalchemy as sa
|
||||
from alembic import op
|
||||
|
||||
revision: str = "c3e9a0d1f4b5"
|
||||
down_revision: str | None = "b7f2a5e81c33"
|
||||
branch_labels: str | Sequence[str] | None = None
|
||||
depends_on: str | Sequence[str] | None = None
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
op.create_table(
|
||||
"factor_composite",
|
||||
sa.Column("id", sa.String(length=32), nullable=False),
|
||||
sa.Column("name", sa.String(length=64), nullable=False),
|
||||
sa.Column("method", sa.String(length=16), nullable=False),
|
||||
sa.Column("description", sa.String(length=300), nullable=False),
|
||||
sa.Column("components_json", sa.Text(), nullable=False),
|
||||
sa.Column("created_at", sa.DateTime(), nullable=False),
|
||||
sa.PrimaryKeyConstraint("id"),
|
||||
sa.UniqueConstraint("name", name="uq_factor_composite_name"),
|
||||
)
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
op.drop_table("factor_composite")
|
||||
@@ -4,6 +4,9 @@
|
||||
模型统一继承 infra.persistence.sqlalchemy.base.Base。
|
||||
"""
|
||||
|
||||
from app.infrastructure.persistence.sqlalchemy.models.composite import ( # noqa: F401
|
||||
FactorCompositeModel,
|
||||
)
|
||||
from app.infrastructure.persistence.sqlalchemy.models.factor import ( # noqa: F401
|
||||
FactorDefinitionModel,
|
||||
)
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
"""因子组合表（M7.2b）。
|
||||
|
||||
factor_composite：可保存/复用的因子组合定义；components 以 JSON 存
|
||||
（组件方向冗余快照自因子注册表，计算时以注册表为准）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import datetime
|
||||
|
||||
from sqlalchemy import DateTime, String, Text
|
||||
from sqlalchemy.orm import Mapped, mapped_column
|
||||
|
||||
from app.infrastructure.persistence.sqlalchemy.base import Base
|
||||
|
||||
|
||||
class FactorCompositeModel(Base):
|
||||
__tablename__ = "factor_composite"
|
||||
|
||||
id: Mapped[str] = mapped_column(String(32), primary_key=True)
|
||||
name: Mapped[str] = mapped_column(String(64), unique=True)
|
||||
method: Mapped[str] = mapped_column(String(16), default="fixed")
|
||||
description: Mapped[str] = mapped_column(String(300), default="")
|
||||
components_json: Mapped[str] = mapped_column(Text)
|
||||
created_at: Mapped[datetime] = mapped_column(DateTime)
|
||||
@@ -0,0 +1,80 @@
|
||||
"""因子组合 Repository 的 SQLAlchemy 实现（M7.2b）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from datetime import datetime
|
||||
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.domain.entities.composite import CompositeComponent, CompositeDefinition
|
||||
from app.infrastructure.persistence.sqlalchemy.models.composite import FactorCompositeModel
|
||||
|
||||
|
||||
class SqlAlchemyCompositeRepository:
|
||||
def __init__(self, session: Session) -> None:
|
||||
self._session = session
|
||||
|
||||
def save(self, definition: CompositeDefinition) -> CompositeDefinition:
|
||||
if not definition.id:
|
||||
raise ValueError("需要 id（由调用方生成）")
|
||||
exists = self._session.get(FactorCompositeModel, definition.id)
|
||||
dup = self._session.scalar(
|
||||
select(FactorCompositeModel)
|
||||
.where(FactorCompositeModel.name == definition.name)
|
||||
.limit(1)
|
||||
)
|
||||
if dup is not None and dup.id != definition.id:
|
||||
raise ValueError(f"组合名已存在：{definition.name}")
|
||||
now = definition.created_at or datetime.now()
|
||||
if exists is None:
|
||||
self._session.add(
|
||||
FactorCompositeModel(
|
||||
id=definition.id,
|
||||
name=definition.name,
|
||||
method=definition.method,
|
||||
description=definition.description,
|
||||
components_json=json.dumps(
|
||||
[c.model_dump() for c in definition.components], ensure_ascii=False
|
||||
),
|
||||
created_at=now,
|
||||
)
|
||||
)
|
||||
else:
|
||||
exists.name = definition.name
|
||||
exists.method = definition.method
|
||||
exists.description = definition.description
|
||||
exists.components_json = json.dumps(
|
||||
[c.model_dump() for c in definition.components], ensure_ascii=False
|
||||
)
|
||||
self._session.flush()
|
||||
return definition
|
||||
|
||||
def get(self, composite_id: str) -> CompositeDefinition | None:
|
||||
row = self._session.get(FactorCompositeModel, composite_id)
|
||||
return _to_entity(row) if row else None
|
||||
|
||||
def list(self) -> list[CompositeDefinition]:
|
||||
rows = self._session.scalars(
|
||||
select(FactorCompositeModel).order_by(FactorCompositeModel.name)
|
||||
).all()
|
||||
return [_to_entity(r) for r in rows]
|
||||
|
||||
def delete(self, composite_id: str) -> bool:
|
||||
row = self._session.get(FactorCompositeModel, composite_id)
|
||||
if row is None:
|
||||
return False
|
||||
self._session.delete(row)
|
||||
return True
|
||||
|
||||
|
||||
def _to_entity(row: FactorCompositeModel) -> CompositeDefinition:
|
||||
return CompositeDefinition(
|
||||
id=row.id,
|
||||
name=row.name,
|
||||
method=row.method,
|
||||
description=row.description,
|
||||
components=[CompositeComponent(**c) for c in json.loads(row.components_json)],
|
||||
created_at=row.created_at,
|
||||
)
|
||||
@@ -0,0 +1,125 @@
|
||||
"""M7.2b 因子组合测试：repo CRUD（幂等/去重）+ /api/composites（含方向填充/404/删除）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pytest
|
||||
from app.api import deps
|
||||
from app.domain.entities.composite import CompositeComponent, CompositeDefinition
|
||||
from app.infrastructure.persistence.sqlalchemy.base import Base
|
||||
from app.infrastructure.persistence.sqlalchemy.repositories.composite_impl import (
|
||||
SqlAlchemyCompositeRepository,
|
||||
)
|
||||
from app.main import app
|
||||
from fastapi.testclient import TestClient
|
||||
from sqlalchemy import create_engine
|
||||
from sqlalchemy.orm import sessionmaker
|
||||
|
||||
|
||||
@pytest.fixture()
|
||||
def session(tmp_path):
|
||||
engine = create_engine(f"sqlite:///{tmp_path / 'c.db'}", future=True)
|
||||
Base.metadata.create_all(engine)
|
||||
Session = sessionmaker(bind=engine, expire_on_commit=False)
|
||||
with Session() as s:
|
||||
yield s
|
||||
|
||||
|
||||
def _comp(name="质量动量", **kw) -> CompositeDefinition:
|
||||
base = dict(
|
||||
name=name,
|
||||
description="测试组合",
|
||||
components=[
|
||||
CompositeComponent(name="momentum_60", weight=0.7, direction="higher_is_better"),
|
||||
CompositeComponent(name="volatility_60", weight=0.3, direction="lower_is_better"),
|
||||
],
|
||||
)
|
||||
base.update(kw)
|
||||
return CompositeDefinition(**base)
|
||||
|
||||
|
||||
class TestCompositeRepository:
|
||||
def test_save_get_list(self, session) -> None:
|
||||
repo = SqlAlchemyCompositeRepository(session)
|
||||
saved = repo.save(_comp().model_copy(update={"id": "CF-TEST-1"}))
|
||||
session.commit()
|
||||
assert saved.id == "CF-TEST-1"
|
||||
got = repo.get("CF-TEST-1")
|
||||
assert got is not None and got.name == "质量动量"
|
||||
assert len(got.components) == 2
|
||||
assert repo.list()[0].components[0].direction == "higher_is_better"
|
||||
|
||||
def test_duplicate_name_rejected(self, session) -> None:
|
||||
repo = SqlAlchemyCompositeRepository(session)
|
||||
repo.save(_comp().model_copy(update={"id": "CF-A"}))
|
||||
session.commit()
|
||||
with pytest.raises(ValueError):
|
||||
repo.save(_comp().model_copy(update={"id": "CF-B"})) # 同名不同 id
|
||||
|
||||
def test_delete(self, session) -> None:
|
||||
repo = SqlAlchemyCompositeRepository(session)
|
||||
repo.save(_comp().model_copy(update={"id": "CF-X"}))
|
||||
session.commit()
|
||||
assert repo.delete("CF-X") is True
|
||||
session.commit()
|
||||
assert repo.get("CF-X") is None
|
||||
assert repo.delete("CF-X") is False
|
||||
|
||||
|
||||
@pytest.fixture()
|
||||
def client(tmp_path):
|
||||
engine = create_engine(f"sqlite:///{tmp_path / 'api.db'}", future=True)
|
||||
Base.metadata.create_all(engine)
|
||||
Session = sessionmaker(bind=engine, expire_on_commit=False)
|
||||
|
||||
def _session_override():
|
||||
with Session() as s:
|
||||
yield s
|
||||
|
||||
app.dependency_overrides[deps.get_session] = _session_override
|
||||
with TestClient(app) as c:
|
||||
yield c
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
|
||||
class TestCompositesApi:
|
||||
def test_crud(self, client) -> None:
|
||||
body = {
|
||||
"name": "质量动量组合",
|
||||
"description": "动量+低波",
|
||||
"components": [
|
||||
{"name": "momentum_60", "weight": 0.7},
|
||||
{"name": "volatility_60", "weight": 0.3},
|
||||
],
|
||||
}
|
||||
created = client.post("/api/composites", json=body)
|
||||
assert created.status_code == 200
|
||||
cid = created.json()["id"]
|
||||
assert cid.startswith("CF-")
|
||||
# 方向由注册表自动填充
|
||||
dirs = {c["name"]: c["direction"] for c in created.json()["components"]}
|
||||
assert dirs == {"momentum_60": "higher_is_better", "volatility_60": "lower_is_better"}
|
||||
|
||||
rows = client.get("/api/composites").json()
|
||||
assert len(rows) == 1
|
||||
detail = client.get(f"/api/composites/{cid}").json()
|
||||
assert detail["name"] == "质量动量组合"
|
||||
|
||||
assert client.delete(f"/api/composites/{cid}").status_code == 200
|
||||
assert client.get(f"/api/composites/{cid}").status_code == 404
|
||||
assert client.delete(f"/api/composites/{cid}").status_code == 404
|
||||
|
||||
def test_unknown_factor_rejected(self, client) -> None:
|
||||
resp = client.post(
|
||||
"/api/composites",
|
||||
json={
|
||||
"name": "坏组合",
|
||||
"components": [{"name": "no_such_factor", "weight": 1}],
|
||||
},
|
||||
)
|
||||
assert resp.status_code == 400
|
||||
assert "no_such_factor" in resp.json()["detail"]
|
||||
|
||||
def test_duplicate_name_400(self, client) -> None:
|
||||
body = {"name": "同名", "components": [{"name": "momentum_60", "weight": 1}]}
|
||||
assert client.post("/api/composites", json=body).status_code == 200
|
||||
assert client.post("/api/composites", json=body).status_code == 400
|
||||
Reference in New Issue
Block a user