487 lines
11 KiB
YAML
487 lines
11 KiB
YAML
# Review Teams API Contract
|
|
# OpenAPI 3.0.3
|
|
|
|
openapi: 3.0.3
|
|
info:
|
|
title: Review Teams API
|
|
version: 1.0.0
|
|
description: |
|
|
API for managing Review Teams and Review Tasks for RFA approval workflow.
|
|
All IDs are UUID strings (publicId) per ADR-019.
|
|
|
|
servers:
|
|
- url: /api/v1
|
|
|
|
tags:
|
|
- name: Review Teams
|
|
- name: Review Tasks
|
|
|
|
paths:
|
|
/review-teams:
|
|
get:
|
|
summary: List Review Teams
|
|
tags: [Review Teams]
|
|
parameters:
|
|
- name: projectId
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: isActive
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
responses:
|
|
'200':
|
|
description: List of review teams
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ReviewTeam'
|
|
|
|
post:
|
|
summary: Create Review Team
|
|
tags: [Review Teams]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateReviewTeamDto'
|
|
responses:
|
|
'201':
|
|
description: Created review team
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ReviewTeam'
|
|
|
|
/review-teams/{publicId}:
|
|
parameters:
|
|
- name: publicId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
|
|
get:
|
|
summary: Get Review Team
|
|
tags: [Review Teams]
|
|
responses:
|
|
'200':
|
|
description: Review team details with members
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ReviewTeamWithMembers'
|
|
|
|
patch:
|
|
summary: Update Review Team
|
|
tags: [Review Teams]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UpdateReviewTeamDto'
|
|
responses:
|
|
'200':
|
|
description: Updated review team
|
|
|
|
delete:
|
|
summary: Soft Delete Review Team
|
|
tags: [Review Teams]
|
|
responses:
|
|
'204':
|
|
description: Deleted
|
|
|
|
/review-teams/{teamId}/members:
|
|
parameters:
|
|
- name: teamId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
|
|
post:
|
|
summary: Add Member to Review Team
|
|
tags: [Review Teams]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AddTeamMemberDto'
|
|
responses:
|
|
'201':
|
|
description: Member added
|
|
|
|
/review-teams/{teamId}/members/{memberId}:
|
|
parameters:
|
|
- name: teamId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: memberId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
|
|
delete:
|
|
summary: Remove Member from Review Team
|
|
tags: [Review Teams]
|
|
responses:
|
|
'204':
|
|
description: Member removed
|
|
|
|
/review-tasks:
|
|
get:
|
|
summary: List Review Tasks (for current user inbox)
|
|
tags: [Review Tasks]
|
|
parameters:
|
|
- name: status
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum: [PENDING, IN_PROGRESS, COMPLETED, DELEGATED, EXPIRED]
|
|
- name: includeDelegated
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
description: Include tasks delegated to user
|
|
responses:
|
|
'200':
|
|
description: List of review tasks
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ReviewTask'
|
|
aggregate:
|
|
$ref: '#/components/schemas/TaskAggregate'
|
|
|
|
/review-tasks/{publicId}:
|
|
parameters:
|
|
- name: publicId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
|
|
get:
|
|
summary: Get Review Task Detail
|
|
tags: [Review Tasks]
|
|
responses:
|
|
'200':
|
|
description: Task details with RFA info
|
|
|
|
post:
|
|
summary: Complete Review Task
|
|
tags: [Review Tasks]
|
|
description: Submit review decision with response code
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CompleteReviewTaskDto'
|
|
responses:
|
|
'200':
|
|
description: Task completed, consensus evaluated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
task:
|
|
$ref: '#/components/schemas/ReviewTask'
|
|
consensus:
|
|
$ref: '#/components/schemas/ConsensusResult'
|
|
|
|
/review-tasks/{publicId}/delegate:
|
|
post:
|
|
summary: Delegate Review Task
|
|
tags: [Review Tasks]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
delegateeUserId:
|
|
type: string
|
|
format: uuid
|
|
reason:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Task delegated
|
|
|
|
/rfa-revisions/{revisionId}/review-status:
|
|
get:
|
|
summary: Get Aggregate Review Status for RFA Revision
|
|
tags: [Review Tasks]
|
|
parameters:
|
|
- name: revisionId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
'200':
|
|
description: Aggregate status across all disciplines
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ReviewAggregateStatus'
|
|
|
|
components:
|
|
schemas:
|
|
ReviewTeam:
|
|
type: object
|
|
properties:
|
|
publicId:
|
|
type: string
|
|
format: uuid
|
|
name:
|
|
type: string
|
|
description:
|
|
type: string
|
|
defaultForRfaTypes:
|
|
type: array
|
|
items:
|
|
type: string
|
|
isActive:
|
|
type: boolean
|
|
memberCount:
|
|
type: integer
|
|
|
|
ReviewTeamWithMembers:
|
|
allOf:
|
|
- $ref: '#/components/schemas/ReviewTeam'
|
|
- type: object
|
|
properties:
|
|
members:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TeamMember'
|
|
|
|
TeamMember:
|
|
type: object
|
|
properties:
|
|
publicId:
|
|
type: string
|
|
format: uuid
|
|
user:
|
|
$ref: '#/components/schemas/UserBrief'
|
|
discipline:
|
|
$ref: '#/components/schemas/DisciplineBrief'
|
|
role:
|
|
type: string
|
|
enum: [REVIEWER, LEAD, MANAGER]
|
|
priorityOrder:
|
|
type: integer
|
|
|
|
ReviewTask:
|
|
type: object
|
|
properties:
|
|
publicId:
|
|
type: string
|
|
format: uuid
|
|
rfaRevisionId:
|
|
type: string
|
|
format: uuid
|
|
team:
|
|
$ref: '#/components/schemas/ReviewTeam'
|
|
discipline:
|
|
$ref: '#/components/schemas/DisciplineBrief'
|
|
assignedTo:
|
|
$ref: '#/components/schemas/UserBrief'
|
|
status:
|
|
type: string
|
|
enum: [PENDING, IN_PROGRESS, COMPLETED, DELEGATED, EXPIRED, CANCELLED]
|
|
dueDate:
|
|
type: string
|
|
format: date
|
|
responseCode:
|
|
$ref: '#/components/schemas/ResponseCodeBrief'
|
|
comments:
|
|
type: string
|
|
isDelegated:
|
|
type: boolean
|
|
|
|
ConsensusResult:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [APPROVED, REJECTED, IN_PROGRESS, SPLIT]
|
|
totalDisciplines:
|
|
type: integer
|
|
completedCount:
|
|
type: integer
|
|
approvedCount:
|
|
type: integer
|
|
rejectedCount:
|
|
type: integer
|
|
vetoTriggered:
|
|
type: boolean
|
|
description: True if any discipline gave Code 3
|
|
|
|
ReviewAggregateStatus:
|
|
type: object
|
|
properties:
|
|
rfaRevisionId:
|
|
type: string
|
|
format: uuid
|
|
totalTasks:
|
|
type: integer
|
|
completedTasks:
|
|
type: integer
|
|
pendingTasks:
|
|
type: integer
|
|
consensusStatus:
|
|
type: string
|
|
enum: [UNANIMOUS_APPROVAL, MAJORITY_APPROVAL, REJECTED, IN_PROGRESS, PENDING]
|
|
perDiscipline:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
discipline:
|
|
$ref: '#/components/schemas/DisciplineBrief'
|
|
taskId:
|
|
type: string
|
|
format: uuid
|
|
status:
|
|
type: string
|
|
responseCode:
|
|
type: string
|
|
|
|
CreateReviewTeamDto:
|
|
type: object
|
|
required: [name, projectId]
|
|
properties:
|
|
name:
|
|
type: string
|
|
minLength: 2
|
|
maxLength: 100
|
|
description:
|
|
type: string
|
|
maxLength: 255
|
|
projectId:
|
|
type: string
|
|
format: uuid
|
|
defaultForRfaTypes:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
UpdateReviewTeamDto:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
minLength: 2
|
|
maxLength: 100
|
|
description:
|
|
type: string
|
|
isActive:
|
|
type: boolean
|
|
|
|
AddTeamMemberDto:
|
|
type: object
|
|
required: [userId, disciplineId]
|
|
properties:
|
|
userId:
|
|
type: string
|
|
format: uuid
|
|
disciplineId:
|
|
type: integer
|
|
role:
|
|
type: string
|
|
enum: [REVIEWER, LEAD, MANAGER]
|
|
default: REVIEWER
|
|
|
|
CompleteReviewTaskDto:
|
|
type: object
|
|
required: [responseCodeId]
|
|
properties:
|
|
responseCodeId:
|
|
type: string
|
|
format: uuid
|
|
description: Selected response code (e.g., 1A, 2, 3)
|
|
comments:
|
|
type: string
|
|
maxLength: 2000
|
|
attachments:
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uuid
|
|
|
|
UserBrief:
|
|
type: object
|
|
properties:
|
|
publicId:
|
|
type: string
|
|
format: uuid
|
|
name:
|
|
type: string
|
|
email:
|
|
type: string
|
|
|
|
DisciplineBrief:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
code:
|
|
type: string
|
|
name:
|
|
type: string
|
|
|
|
ResponseCodeBrief:
|
|
type: object
|
|
properties:
|
|
publicId:
|
|
type: string
|
|
format: uuid
|
|
code:
|
|
type: string
|
|
descriptionTh:
|
|
type: string
|
|
descriptionEn:
|
|
type: string
|
|
|
|
TaskAggregate:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: integer
|
|
byStatus:
|
|
type: object
|
|
additionalProperties:
|
|
type: integer
|