613 lines
18 KiB
Markdown
613 lines
18 KiB
Markdown
## Requirements
|
|
|
|
- team has its own dashboard tab in the UI
|
|
- COIs for a team are only visible to that team members and super admins.
|
|
- team can have multiple checklists
|
|
- separate email agents
|
|
- user can belong to multiple teams
|
|
|
|
---
|
|
|
|
## RBAC
|
|
|
|
### Permissions
|
|
|
|
```python
|
|
class Permission(models.TextChoices):
|
|
CONTRACT_VIEW = "contract:view"
|
|
CONTRACT_CREATE = "contract:create"
|
|
CONTRACT_ANALYZE = "contract:analyze"
|
|
CONTRACT_DELETE = "contract:delete"
|
|
|
|
CHECKLIST_VIEW = "checklist:view"
|
|
CHECKLIST_CREATE = "checklist:create"
|
|
CHECKLIST_EDIT = "checklist:edit"
|
|
CHECKLIST_DELETE = "checklist:delete"
|
|
CHECKLIST_SET_ACTIVE = "checklist:set_active"
|
|
|
|
TEAM_VIEW = "team:view"
|
|
TEAM_VIEW_ALL = "team:view:all" # super admin - see all teams
|
|
TEAM_MANAGE_MEMBERS = "team:manage_members"
|
|
TEAM_EDIT_SETTINGS = "team:edit_settings"
|
|
TEAM_DELETE = "team:delete"
|
|
|
|
EMAIL_AGENT_VIEW = "email_agent:view"
|
|
EMAIL_AGENT_CONFIGURE = "email_agent:configure"
|
|
|
|
USER_INVITE = "user:invite"
|
|
USER_MANAGE = "user:manage"
|
|
```
|
|
|
|
```python
|
|
class Role():
|
|
class RoleType(models.TextChoices):
|
|
ADMIN = "ADMIN"
|
|
MASTER = "MASTER"
|
|
VIEWER = "VIEWER"
|
|
|
|
name = models.CharField(max_length=50, unique=True)
|
|
description = models.TextField(blank=True)
|
|
permissions = models.JSONField(default=list)
|
|
|
|
is_system = models.BooleanField(default=False)
|
|
|
|
|
|
ROLE_PERMISSIONS = {
|
|
"ADMIN": [
|
|
"contract:view", "contract:create", "contract:analyze", "contract:delete",
|
|
"checklist:view", "checklist:create", "checklist:edit", "checklist:delete", "checklist:set_active",
|
|
"team:view", "team:view:all", "team:manage_members", "team:edit_settings", "team:delete",
|
|
"email_agent:view", "email_agent:configure",
|
|
"user:invite", "user:manage",
|
|
],
|
|
"MASTER": [
|
|
"contract:view", "contract:create", "contract:analyze",
|
|
"checklist:view", "checklist:create", "checklist:edit", "checklist:set_active",
|
|
"team:view", "team:manage_members",
|
|
"email_agent:view",
|
|
],
|
|
"VIEWER": [
|
|
"contract:view",
|
|
"checklist:view",
|
|
"team:view",
|
|
],
|
|
}
|
|
```
|
|
|
|
### Permission
|
|
|
|
```python
|
|
def get_user_permissions(user: User, team_id: str = None) -> set:
|
|
membership = TeamMembership.objects.filter(
|
|
user=user,
|
|
team_id=team_id,
|
|
deleted_at__isnull=True
|
|
).select_related("role").first()
|
|
|
|
if not membership:
|
|
return set()
|
|
|
|
return set(membership.role.permissions)
|
|
|
|
def has_permission(user: User, permission: str, team_id: str = None) -> bool:
|
|
return permission in get_user_permissions(user, team_id)
|
|
|
|
|
|
def has_team_access(user: User, team_id: str) -> bool:
|
|
if has_permission(user, "team:view:all"):
|
|
return True
|
|
|
|
return TeamMembership.objects.filter(
|
|
user=user,
|
|
team_id=team_id,
|
|
deleted_at__isnull=True
|
|
).exists()
|
|
```
|
|
|
|
```python
|
|
def require_permission(permission: str, team_id: UUID)
|
|
def decorator(view_func):
|
|
@wraps(view_func)
|
|
def wrapper(request, *args, **kwargs):
|
|
user = request.user
|
|
team_id = kwargs.get(team_id_param) or request.data.get(team_id_param)
|
|
|
|
if not has_permission(user, permission, team_id):
|
|
return Response(
|
|
{ "error": "Permission denied" },
|
|
status=status.HTTP_403_FORBIDDEN
|
|
)
|
|
|
|
return view_func(request, *args, **kwargs)
|
|
return wrapper
|
|
return decorator
|
|
|
|
|
|
def require_team_access(team_id_param: str = "team_id"):
|
|
"""Decorator to check team membership"""
|
|
def decorator(view_func):
|
|
@wraps(view_func)
|
|
def wrapper(request, *args, **kwargs):
|
|
team_id = kwargs.get(team_id_param)
|
|
|
|
if not has_team_access(request.user, team_id):
|
|
return Response(
|
|
{"error": "Team not found"},
|
|
status=status.HTTP_404_NOT_FOUND
|
|
)
|
|
|
|
return view_func(request, *args, **kwargs)
|
|
return wrapper
|
|
return decorator
|
|
```
|
|
|
|
### Usage in Views
|
|
|
|
```python
|
|
@api_view(["POST"])
|
|
@permission_classes([IsAuthenticated])
|
|
@require_team_access("team_id")
|
|
@require_permission("contract:create", "team_id")
|
|
def upload_contract(request, team_id):
|
|
# user has access to team AND has contract:create permission
|
|
```
|
|
|
|
---
|
|
|
|
## Team
|
|
|
|
```python
|
|
class Team():
|
|
name = models.CharField(max_length=200)
|
|
description = models.TextField(blank=True)
|
|
|
|
organization = models.ForeignKey(
|
|
"Organization",
|
|
on_delete=models.CASCADE,
|
|
related_name="teams"
|
|
)
|
|
|
|
is_default = models.BooleanField(default=False)
|
|
settings = models.JSONField(default=dict)
|
|
```
|
|
|
|
```python
|
|
class TeamMembership():
|
|
user = models.ForeignKey(
|
|
"User",
|
|
on_delete=models.CASCADE,
|
|
related_name="team_memberships"
|
|
)
|
|
|
|
team = models.ForeignKey(
|
|
Team,
|
|
on_delete=models.CASCADE,
|
|
related_name="memberships"
|
|
)
|
|
|
|
role = models.ForeignKey(
|
|
"Role",
|
|
on_delete=models.PROTECT,
|
|
related_name="team_memberships"
|
|
)
|
|
|
|
added_by = models.ForeignKey(
|
|
"User",
|
|
on_delete=models.SET_NULL,
|
|
null=True,
|
|
related_name="memberships_added"
|
|
)
|
|
```
|
|
|
|
```python
|
|
class TeamEmailAgent(BaseModel):
|
|
team = models.OneToOneField(
|
|
Team,
|
|
on_delete=models.CASCADE,
|
|
related_name="email_agent"
|
|
)
|
|
|
|
provider_type = models.CharField(
|
|
max_length=20,
|
|
choices=ProviderType.choices,
|
|
default=ProviderType.MICROSOFT
|
|
)
|
|
|
|
inbox_email = models.EmailField(unique=True)
|
|
|
|
ms_client_id = models.CharField(max_length=500, blank=True)
|
|
ms_client_secret = models.CharField(max_length=500, blank=True) # maybe encrypt this
|
|
ms_tenant_id = models.CharField(max_length=500, blank=True)
|
|
|
|
subscription_id = models.CharField(max_length=500, null=True, blank=True)
|
|
subscription_expiry = models.DateTimeField(null=True, blank=True)
|
|
|
|
# processing settings
|
|
# {
|
|
# "default_checklist_id": "uuid",
|
|
# "automated_reminder": {} .....
|
|
# }
|
|
processing_settings = models.JSONField(default=dict)
|
|
|
|
enabled = models.BooleanField(default=False)
|
|
|
|
def get_access_token(self) -> str:
|
|
"""Get OAuth access token for email operations"""
|
|
from assistantService.services.graph_service.service import GraphEmailService
|
|
|
|
graph = GraphEmailService()
|
|
return graph.generate_access_token(
|
|
client_id=self.ms_client_id,
|
|
client_secret=self.ms_client_secret,
|
|
tenant_id=self.ms_tenant_id
|
|
)
|
|
```
|
|
|
|
```python
|
|
class Contract():
|
|
# existing fields
|
|
|
|
team = models.ForeignKey(
|
|
"Team",
|
|
on_delete=models.SET_NULL,
|
|
null=True,
|
|
blank=True,
|
|
related_name="contracts"
|
|
)
|
|
```
|
|
|
|
```python
|
|
class Checklist(BaseModel):
|
|
# existing fields
|
|
|
|
# NULL might mean this checklist is available org wide....
|
|
team = models.ForeignKey(
|
|
"Team",
|
|
on_delete=models.SET_NULL,
|
|
null=True,
|
|
blank=True,
|
|
related_name="checklists"
|
|
)
|
|
```
|
|
|
|
## Team Management
|
|
|
|
```python
|
|
class TeamService:
|
|
def __init__(self, user: User):
|
|
self.user = user
|
|
|
|
def _check_permission(self, permission: str, team_id: str = None):
|
|
if not has_permission(self.user, permission, team_id):
|
|
raise PermissionError(f"Missing permission: {permission}")
|
|
|
|
@transaction.atomic
|
|
def create_team(
|
|
self,
|
|
organization_id: str,
|
|
name: str,
|
|
description: str = "",
|
|
settings: Dict = None,
|
|
) -> Team:
|
|
# only admins can create teams
|
|
self._check_permission("team:view:all")
|
|
|
|
team = Team.objects.create(
|
|
organization_id=organization_id,
|
|
name=name,
|
|
description=description,
|
|
settings=settings or {}
|
|
)
|
|
|
|
# creator becomes admin of this team
|
|
admin_role = Role.objects.get(name="ADMIN")
|
|
TeamMembership.objects.create(
|
|
user=self.user,
|
|
team=team,
|
|
role=admin_role,
|
|
added_by=self.user
|
|
)
|
|
|
|
return team
|
|
|
|
def get_user_teams(self, user: User) -> List[Dict[str, Any]]:
|
|
"""Get all teams a user has access to"""
|
|
|
|
memberships = TeamMembership.objects.filter(
|
|
user=user,
|
|
deleted_at__isnull=True
|
|
).select_related("team", "role").order_by("team__settings__order", "team__name")
|
|
|
|
teams = []
|
|
for membership in memberships:
|
|
team = membership.team
|
|
teams.append({
|
|
"id": str(team.id),
|
|
"name": team.name,
|
|
"description": team.description,
|
|
"settings": team.settings,
|
|
"role": membership.role.name,
|
|
"is_default": team.is_default,
|
|
})
|
|
|
|
return teams
|
|
|
|
@transaction.atomic
|
|
def add_member(
|
|
self,
|
|
team_id: str,
|
|
user_id: str,
|
|
role_name: str,
|
|
) -> TeamMembership:
|
|
# requires team:manage_members permission
|
|
self._check_permission("team:manage_members", team_id)
|
|
|
|
team = Team.objects.get(id=team_id)
|
|
user = User.objects.get(RowKey=user_id, organization_id=team.organization_id)
|
|
role = Role.objects.get(name=role_name.upper())
|
|
|
|
# prevent assigning higher role than own
|
|
my_membership = TeamMembership.objects.get(user=self.user, team=team)
|
|
if self._role_level(role) > self._role_level(my_membership.role):
|
|
raise PermissionError("Cannot assign role higher than your own")
|
|
|
|
membership, created = TeamMembership.objects.update_or_create(
|
|
team=team,
|
|
user=user,
|
|
defaults={
|
|
"role": role,
|
|
"added_by": self.user,
|
|
"deleted_at": None,
|
|
}
|
|
)
|
|
return membership
|
|
|
|
def _role_level(self, role: Role) -> int:
|
|
levels = {"VIEWER": 1, "MASTER": 2, "ADMIN": 3}
|
|
return levels.get(role.name, 0)
|
|
|
|
def remove_member(self, team_id: str, user_id: str) -> bool:
|
|
self._check_permission("team:manage_members", team_id)
|
|
|
|
membership = TeamMembership.objects.filter(
|
|
team_id=team_id,
|
|
user_id=user_id,
|
|
deleted_at__isnull=True
|
|
).first()
|
|
|
|
if membership:
|
|
membership.deleted_at = timezone.now()
|
|
membership.save()
|
|
return True
|
|
|
|
return False
|
|
|
|
def get_team_stats(self, team_id: str) -> Dict[str, int]:
|
|
from assistantService.models import Contract
|
|
|
|
today = date.today()
|
|
next_30 = today + timedelta(days=30)
|
|
|
|
contracts = Contract.objects.filter(
|
|
team_id=team_id,
|
|
deleted_at__isnull=True
|
|
)
|
|
|
|
return {
|
|
"total_contracts": contracts.count(),
|
|
"pending": contracts.filter(analysis_status="PENDING").count(),
|
|
"accepted": contracts.filter(analysis_status="ACCEPTED").count(),
|
|
"rejected": contracts.filter(analysis_status="REJECTED").count(),
|
|
"expiring_in_30_days": contracts.filter(
|
|
expiry_date__range=(today, next_30)
|
|
).count(),
|
|
"expired": contracts.filter(expiry_date__lt=today).count(),
|
|
"members": TeamMembership.objects.filter(
|
|
team_id=team_id,
|
|
deleted_at__isnull=True
|
|
).count(),
|
|
}
|
|
```
|
|
|
|
## Dashboard Tabs
|
|
|
|
```python
|
|
class DashboardService:
|
|
def __init__(self, user: User):
|
|
self.user = user
|
|
|
|
def get_dashboard(
|
|
self,
|
|
team_id: str,
|
|
page: int = 1,
|
|
page_size: int = 10,
|
|
filters: Optional[Dict] = None
|
|
) -> Dict[str, Any]:
|
|
# uses has_team_access from RBAC
|
|
if not has_team_access(self.user, team_id):
|
|
raise PermissionError("You don't have access to this team")
|
|
|
|
team = Team.objects.get(id=team_id)
|
|
|
|
query = Contract.objects.filter(
|
|
team_id=team_id,
|
|
deleted_at__isnull=True
|
|
)
|
|
|
|
if filters:
|
|
query = self._apply_filters(query, filters)
|
|
|
|
query = query.order_by("-created_at")
|
|
|
|
query = query.select_related(
|
|
"current_version",
|
|
"active_checklist",
|
|
"uploaded_by"
|
|
)
|
|
|
|
paginator = Paginator(query, page_size)
|
|
page_obj = paginator.get_page(page)
|
|
|
|
contracts = [
|
|
self._format_contract(c, team.organization.settings.get("timezone", "UTC"))
|
|
for c in page_obj
|
|
]
|
|
|
|
return {
|
|
"team": {
|
|
"id": str(team.id),
|
|
"name": team.name,
|
|
"settings": team.settings,
|
|
},
|
|
"contracts": contracts,
|
|
"pagination": {
|
|
"current_page": page,
|
|
"total_pages": paginator.num_pages,
|
|
"total_count": paginator.count,
|
|
"has_next": page_obj.has_next(),
|
|
"has_previous": page_obj.has_previous(),
|
|
},
|
|
"filters": self._get_filter_options(team_id),
|
|
}
|
|
```
|
|
|
|
### Email Agent Configuration
|
|
|
|
```python
|
|
class TeamEmailAgentService:
|
|
def __init__(self, user: User):
|
|
self.user = user
|
|
|
|
def get_config(self, team_id: str) -> Dict[str, Any]:
|
|
if not has_permission(self.user, "email_agent:view", team_id):
|
|
raise PermissionError("Cannot view email agent config")
|
|
|
|
team = Team.objects.get(id=team_id)
|
|
|
|
try:
|
|
agent = team.email_agent
|
|
return {
|
|
"is_configured": True,
|
|
"inbox_email": agent.inbox_email,
|
|
"provider_type": agent.provider_type,
|
|
"is_enabled": agent.is_enabled,
|
|
"processing_settings": agent.processing_settings,
|
|
"subscription_status": {
|
|
"active": agent.subscription_id is not None,
|
|
"expires_at": agent.subscription_expiry.isoformat() if agent.subscription_expiry else None,
|
|
},
|
|
"last_sync_at": agent.last_sync_at.isoformat() if agent.last_sync_at else None,
|
|
}
|
|
except TeamEmailAgent.DoesNotExist:
|
|
return {
|
|
"is_configured": False,
|
|
}
|
|
|
|
@transaction.atomic
|
|
def configure(
|
|
self,
|
|
team_id: str,
|
|
inbox_email: str,
|
|
ms_client_id: str,
|
|
ms_client_secret: str,
|
|
ms_tenant_id: str,
|
|
processing_settings: Dict = None
|
|
) -> TeamEmailAgent:
|
|
# only ADMIN can configure email agent
|
|
if not has_permission(self.user, "email_agent:configure", team_id):
|
|
raise PermissionError("Cannot configure email agent")
|
|
|
|
team = Team.objects.get(id=team_id)
|
|
|
|
graph = GraphEmailService()
|
|
try:
|
|
token = graph.generate_access_token(
|
|
client_id=ms_client_id,
|
|
client_secret=ms_client_secret,
|
|
tenant_id=ms_tenant_id
|
|
)
|
|
except Exception as e:
|
|
raise ValueError(f"Invalid Microsoft Graph credentials: {e}")
|
|
|
|
agent, created = TeamEmailAgent.objects.update_or_create(
|
|
team=team,
|
|
defaults={
|
|
"inbox_email": inbox_email,
|
|
"ms_client_id": ms_client_id,
|
|
"ms_client_secret": ms_client_secret, # TODO: encrypt
|
|
"ms_tenant_id": ms_tenant_id,
|
|
"processing_settings": processing_settings or {},
|
|
}
|
|
)
|
|
|
|
return agent
|
|
|
|
def enable(self, team_id: str) -> TeamEmailAgent:
|
|
if not has_permission(self.user, "email_agent:configure", team_id):
|
|
raise PermissionError("Cannot enable email agent")
|
|
|
|
agent = TeamEmailAgent.objects.get(team_id=team_id)
|
|
|
|
if not agent.ms_client_id:
|
|
raise ValueError("Email agent not configured")
|
|
|
|
subscription = self._create_subscription(agent)
|
|
|
|
agent.is_enabled = True
|
|
agent.subscription_id = subscription["id"]
|
|
agent.subscription_expiry = subscription["expirationDateTime"]
|
|
agent.save()
|
|
|
|
return agent
|
|
|
|
def disable(self, team_id: str) -> TeamEmailAgent:
|
|
if not has_permission(self.user, "email_agent:configure", team_id):
|
|
raise PermissionError("Cannot disable email agent")
|
|
|
|
agent = TeamEmailAgent.objects.get(team_id=team_id)
|
|
|
|
if agent.subscription_id:
|
|
self._delete_subscription(agent)
|
|
|
|
agent.is_enabled = False
|
|
agent.subscription_id = None
|
|
agent.subscription_expiry = None
|
|
agent.save()
|
|
|
|
return agent
|
|
```
|
|
|
|
---
|
|
|
|
## APIs
|
|
|
|
```python
|
|
urlpatterns = [
|
|
# team management
|
|
path("", views.list_teams), # team:view
|
|
path("", views.create_team), # team:view:all (admin only)
|
|
path("<uuid:team_id>/", views.get_team), # team:view + membership
|
|
path("<uuid:team_id>/", views.update_team), # team:edit_settings
|
|
path("<uuid:team_id>/", views.delete_team), # team:delete
|
|
|
|
# members
|
|
path("<uuid:team_id>/members/", views.list_members), # team:view
|
|
path("<uuid:team_id>/members/", views.add_member), # team:manage_members
|
|
path("<uuid:team_id>/members/<uuid:user_id>/", views.remove_member), # team:manage_members
|
|
path("<uuid:team_id>/members/<uuid:user_id>/role/", views.update_member_role),# team:manage_members
|
|
|
|
# dashboard
|
|
path("<uuid:team_id>/dashboard/", views.get_dashboard), # contract:view
|
|
path("<uuid:team_id>/dashboard/stats/", views.get_dashboard_stats),
|
|
|
|
# checklists
|
|
path("<uuid:team_id>/checklists/", views.list_team_checklists), # checklist:view
|
|
|
|
# email agent
|
|
path("<uuid:team_id>/email-agent/", views.get_email_agent_config), # email_agent:view
|
|
path("<uuid:team_id>/email-agent/", views.configure_email_agent), # email_agent:configure
|
|
path("<uuid:team_id>/email-agent/enable/", views.enable_email_agent), # email_agent:configure
|
|
path("<uuid:team_id>/email-agent/disable/", views.disable_email_agent),
|
|
]
|
|
```
|