linyuhang
/
PMFlow
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
PMFlow/docs/architecture/API_CONTRACTS.md

8.7 KiB
Raw Blame History

API CONTRACTS

PMFlow OS

POST /pmflow-os/change-sets/{change_set_id}/commit

  • Purpose: commit reviewed ChangeSet items into the official project truth layer.
  • Auth: project member, OWNER, or REVIEWER; tenant comes from JWT.
  • Request body:
    • item_ids?: string[] optional; default commits all accepted / edited items.
    • mode: "atomic" required for C2 V1.
    • note?: string audit note only.
  • Behavior:
    • Processes only accepted / edited ChangeItems.
    • C2 V1 is atomic: any eligible item write failure rolls back the whole commit.
    • Required C2 objectType support: Requirement / Decision / Task / Risk.
    • Optional C2 objectType support: Release.
    • Unsupported for C2 V1: ModelDecision / MetricSignal, which must fail with 422 unsupported_object_type.
    • Requirement / Decision / Risk / Release write to truth_nodes.
    • Task writes truth_nodes(node_type='task') plus tasks.truth_node_id.
    • High-risk items require item-level approval with decision in ('approved','edited') and after_status in ('accepted','edited').
  • Response data:
    • changeSet: { id, status, rawStatus, committedAt, committedItemIds, skippedItemIds, failedItemIds }
    • committedItems[]: { changeItemId, objectType, targetType, targetId, status, evidenceIds, semanticFactStatus }
    • skippedItems[]: { changeItemId, objectType, status, reason }
    • failedItems[]: { changeItemId, objectType, code, message }
    • projectTruthState?: optional backend projection after commit.
  • Failure semantics:
    • 404 changeset_not_found
    • 409 changeset_not_reviewed
    • 409 changeset_already_committed
    • 409 no_accepted_items
    • 409 high_risk_approval_required
    • 422 invalid_commit_item_ids
    • 422 unsupported_object_type
    • 422 invalid_change_payload
    • 500 commit_failed

Signal & SSTC

GET /projects/{project_id}/signals

  • Response data:
    • items[] includes planner fields:
      • planner_status: "pending" | "completed" | "failed"
      • planner_analyzed_at: string | null
      • planner_assignee_user_id: string | null
      • strategic_analysis: object

Model Routing

GET /model-routing/functions/{function_name}

  • Purpose: query function-level advanced routing override. This is an admin/advanced entry, not the default product UI for members or team leads.
  • Response data:
    • function_name
    • tier
    • source: "default" | "override"

PUT /model-routing/functions/{function_name}

  • Auth: manager/admin only
  • Request body:
    • tier
  • Side effects:
    • persist override into integrations(type='model_routing')
    • append audit to operation_logs

AI Routing & Providers

  • UI placement: these endpoints power the team-level AI 运营中心 under /ai-config; they are not project-scoped and must not be presented as per-project provider/model settings.

GET /ai-routing/overview

  • Purpose: productized AI routing overview for team leads and AI operators.
  • Auth: OWNER or REVIEWER via can_view_ai_policy.
  • Response data:
    • control_plane: { version, source, updated_at, baseline_note }
    • slots[]: low/high slot summaries with Chinese labels, provider/model display summary, connection state, and masked key status.
    • metrics: recent 24h/7d calls, failures, failure rate, escalation rate, structured failure rate, average latency, and cost estimate.
    • diagnostics[]: risk cards such as env key override, high slot unavailable, same runtime for low/high, protected downgrade, structured failure spike, or local Ollama scope risk.
  • Boundary: no cleartext key, api_env, prompt, raw provider secret, raw error, or raw routing meta.

GET /ai-routing/team-policy

  • Purpose: team-lead-facing business policy view for project launch, requirement structuring, task breakdown, assignee matching, internal QA, external query, Feishu understanding, and Feishu reply.
  • Auth: OWNER or REVIEWER.
  • Response data:
    • strategy: quality_first | balanced | speed_first
    • scenes[]: Chinese business scene policies, preferred mode, escalation rule, fallback behavior, and editable business note.
    • automation_boundary, budget_guard, quality_targets, updated_at, updated_by
  • Boundary: team policy is saved product governance state only; it does not rewrite llm_service runtime routing in v1.

PUT /ai-routing/team-policy

  • Purpose: save team AI policy display/governance state.
  • Auth: OWNER only via can_approve_ai_routing_change.
  • Request body:
    • strategy?: "quality_first" | "balanced" | "speed_first"
    • scenes?: [{ key, policy, mode?, human_confirmation?, protected? }]
    • automation_boundary?: string
    • budget_guard?: { enabled?: boolean, monthly_budget_cny?: number | null, alert_threshold_ratio?: number }
    • quality_targets?: string[]
  • Side effects:
    • persist into integrations(type='ai_team_policy')
    • append operation_logs(entity_type='ai_routing_policy')
  • Boundary: never writes backend/.control_plane/pmflow-routing-rules.json, provider secrets, or model-routing overrides.

GET /ai-routing/admin-console

  • Purpose: AI admin/operator console aggregating provider connection summaries, low/high slots, business-scene routes, recent failure samples, protected scenes, and env override diagnostics.
  • Auth: OWNER or REVIEWER.
  • Response data:
    • providers[]: display-only provider health and masked key state.
    • slots[]: fast/deep slot summaries.
    • scene_routes[]: scene label, mode, contract, protection state; raw function_name may only be present in admin data and must be hidden by default in UI advanced details.
    • recent_failures[]: sanitized failure samples without raw error or prompt.
    • protected_scenes[], environment_overrides[], diagnostics[]

POST /ai-routing/diagnostics/run

  • Purpose: run read-only diagnostics for routing/provider health.
  • Auth: OWNER or REVIEWER via can_operate_ai_routing.
  • Side effects: none; does not modify provider, slot, team policy, or runtime routing.

PMFlow OS Adaptive Capacity

All endpoints return { code, message, data }. Project members may read. Override simulate/apply requires OWNER or REVIEWER; write endpoints only persist capacity override audit records and must not assign tasks, request review, write ChangeSet, or mutate Project Memory.

GET /pmflow-os/projects/{project_id}/capacity-plan?date=YYYY-MM-DD

  • Purpose: compute the daily adaptive human capacity plan from current truth-state, reviewer routing, execution summary, workspace bindings, user projects, legacy workload reference, and active overrides.
  • Response data:
    • projectId, date, generatedAt
    • teamDemandMix
    • teamEffectiveMinutes, teamPlannedTouchMinutes
    • memberPlans[]: base/effective minutes, dynamic suggestedBaseline, current mix, planned touch minutes, status, remaining minutes, bottleneck, fatigue risk, risk density, canTakeMore, manual override, explanations
    • humanTouches[]: source, target href, work type, estimated minutes, risk, urgency, binding, assigned user, context readiness, AI reduction potential
    • warnings, recommendations
  • Boundary: daily plan is computed at read time. Do not persist fixed baselines or daily snapshots.

POST /pmflow-os/projects/{project_id}/capacity-overrides/simulate

  • Purpose: simulate a manager capacity override before applying it.
  • Request body: PMFlowCapacityOverridePayload
  • Response data: { beforePlan, afterPlan, impactSummary, warnings }
  • Boundary: no database write and no assignment side effect.

POST /pmflow-os/projects/{project_id}/capacity-overrides

  • Purpose: apply a manager override and persist audit in human_capacity_overrides.
  • Request body: PMFlowCapacityOverridePayload
  • Response data: PMFlowCapacityOverrideRecord
  • Side effects: insert one override audit row only.
  • Boundary: reason is required; default expiry is same day 23:59 if omitted. Overtime increases time budget but must not clear fatigue or quality risk.

GET /pmflow-os/projects/{project_id}/capacity-overrides?date=YYYY-MM-DD

  • Purpose: list override audit records for the given day.
  • Response data: PMFlowCapacityOverrideRecord[]

GET /pmflow-os/projects/{project_id}/execution-capabilities

  • Addition: response data may include adaptiveCapacitySummary: DailyCapacityPlan.

Task Briefs

GET /task-briefs/center

  • Purpose: list generated brief cards

GET /task-briefs/templates

  • Purpose: list templates

POST /task-briefs/templates

  • Purpose: create template

PUT /task-briefs/templates/{template_id}

  • Purpose: update template

GET /task-briefs/runs

  • Purpose: list generation runs

POST /task-briefs/generate

  • Purpose: generate one task brief run

GET /task-briefs/contract-sync

  • Purpose: expose docs/contract sync status snapshot