0.2.23: link GP entities to their investor account for auto asset balances

Ten31 LLC (and any GP/mgmt entity) can be linked to its investor account,
so its Assets tab shows its real capital-account balance in each fund,
pulled live from the eNAV capital accounts instead of manual entry.

- entities.linked_user_id (migration c9d0e1f2a3b4) + EntityCreate/Update/
  Response fields; validated to be an investor account.
- Edit-entity form gains a "Linked investor account" picker for GP/mgmt.
- Assets tab now auto-lists the linked account's balance per fund (the
  earlier manual-stakes API remains but is no longer used by the UI).

Verified: 13/13 backend tests pass; alembic head c9d0e1f2a3b4; frontend
tsc + vite build clean.

backend/alembic/versions/c9d0e1f2a3b4_entity_linked_user.py

@@ -0,0 +1,29 @@
+"""add entities.linked_user_id (link a GP entity to its investor account)
+
+Revision ID: c9d0e1f2a3b4
+Revises: b8c9d0e1f2a3
+Create Date: 2026-07-01 10:45:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = 'c9d0e1f2a3b4'
+down_revision: Union[str, None] = 'b8c9d0e1f2a3'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('entities', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('linked_user_id', sa.Integer(), nullable=True))
+    op.create_index('ix_entities_linked_user_id', 'entities', ['linked_user_id'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_entities_linked_user_id', table_name='entities')
+    with op.batch_alter_table('entities', schema=None) as batch_op:
+        batch_op.drop_column('linked_user_id')

backend/ten31portal/models.py

@@ -87,6 +87,9 @@ class Entity(SQLModel, table=True):
     vintage_year: int | None = None
     fund_size_cents: int | None = None
     status: EntityStatus = Field(default=EntityStatus.active)
+    # For a GP/mgmt entity that is also an LP with capital accounts (e.g. Ten31 LLC), link to
+    # its investor account so its Assets view can pull real per-fund balances from the eNAV.
+    linked_user_id: int | None = Field(default=None, foreign_key="users.id", index=True)
     created_at: datetime = Field(default_factory=datetime.utcnow)
 
 

backend/ten31portal/routers/entity_router.py

@@ -174,12 +174,22 @@ def get_entity(
     return EntityResponse.model_validate(entity, from_attributes=True)
 
 
+def _validate_linked_user(linked_user_id: int | None, session: Session) -> None:
+    """A linked account (for a GP entity that is also an LP) must be an investor account."""
+    if linked_user_id is None:
+        return
+    linked = session.get(User, linked_user_id)
+    if linked is None or linked.role != UserRole.investor:
+        raise HTTPException(status_code=400, detail="Linked account must be an investor account.")
+
+
 @router.post("", status_code=201)
 def create_entity(
     body: EntityCreate,
     user: User = Depends(require_writer),
     session: Session = Depends(get_session),
 ) -> EntityResponse:
+    _validate_linked_user(body.linked_user_id, session)
     entity = Entity(**body.model_dump())
     session.add(entity)
     session.flush()
@@ -200,6 +210,8 @@ def update_entity(
     if entity is None:
         raise HTTPException(status_code=404, detail="Entity not found")
     changes = body.model_dump(exclude_unset=True)
+    if "linked_user_id" in changes:
+        _validate_linked_user(changes["linked_user_id"], session)
     for key, val in changes.items():
         setattr(entity, key, val)
     session.add(entity)

backend/ten31portal/schemas.py

@@ -91,6 +91,7 @@ class EntityCreate(BaseModel):
     type: EntityType
     vintage_year: int | None = None
     fund_size_cents: int | None = None
+    linked_user_id: int | None = None
 
 
 class EntityUpdate(BaseModel):
@@ -99,6 +100,7 @@ class EntityUpdate(BaseModel):
     vintage_year: int | None = None
     fund_size_cents: int | None = None
     status: EntityStatus | None = None
+    linked_user_id: int | None = None
 
 
 class EntityResponse(BaseModel):
@@ -108,6 +110,7 @@ class EntityResponse(BaseModel):
     vintage_year: int | None
     fund_size_cents: int | None
     status: EntityStatus
+    linked_user_id: int | None = None
     created_at: datetime
 
 

backend/tests/test_entity_link.py

@@ -0,0 +1,31 @@
+"""Linking a GP entity to its investor account (so Assets can pull real balances)."""
+
+from tests.conftest import make_user
+from ten31portal.models import Entity, EntityType, UserRole
+
+
+def test_link_entity_to_investor(auth_client, session):
+    inv = make_user(session, username="ten31llc", role=UserRole.investor, name="Ten31 LLC")
+    gp = Entity(name="Ten31 LLC", type=EntityType.gp)
+    session.add(gp)
+    session.commit()
+    session.refresh(gp)
+
+    linked = auth_client.patch(f"/api/entities/{gp.id}", json={"linked_user_id": inv.id})
+    assert linked.status_code == 200, linked.text
+    assert linked.json()["linked_user_id"] == inv.id
+
+    # Unlink.
+    unlinked = auth_client.patch(f"/api/entities/{gp.id}", json={"linked_user_id": None})
+    assert unlinked.status_code == 200
+    assert unlinked.json()["linked_user_id"] is None
+
+
+def test_link_rejects_non_investor(auth_client, session):
+    staff = make_user(session, username="ops2", role=UserRole.operations)
+    gp = Entity(name="Mgmt Co", type=EntityType.mgmt_co)
+    session.add(gp)
+    session.commit()
+    session.refresh(gp)
+    resp = auth_client.patch(f"/api/entities/{gp.id}", json={"linked_user_id": staff.id})
+    assert resp.status_code == 400