284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
123 lines
7.0 KiB
Markdown
123 lines
7.0 KiB
Markdown
# PRD: Complete OpenAPI Documentation Coverage
|
|
|
|
## Status
|
|
|
|
Draft created 2026-04-24.
|
|
|
|
## Problem Statement
|
|
|
|
The generated Alga PSA OpenAPI specs still contain hundreds of route-inventory placeholder operations. Placeholder operations have generic summaries/descriptions, empty request/response schemas, incomplete auth information, and no source-grounded notes about tenant scoping, ID provenance, current implementation gaps, or status-code behavior.
|
|
|
|
This limits SDK generation, API discoverability, integration accuracy, AI/tool-call grounding, and QA confidence. The ongoing work has already replaced placeholders for the first 80 operations. The remaining work needs a durable, testable plan so future batches can continue consistently.
|
|
|
|
## User Value
|
|
|
|
- API consumers can understand required inputs, output envelopes, auth requirements, tenant behavior, and failure modes without reading source.
|
|
- Generated SDK/docs become safer to use because route metadata is canonical instead of inventory-derived.
|
|
- Internal agents and tooling can reason about API capabilities using accurate OpenAPI descriptions.
|
|
- Future maintainers can continue the batch process without losing context or repeating investigation work.
|
|
|
|
## Goals
|
|
|
|
1. Replace all remaining generated placeholder OpenAPI operations in CE and EE specs with source-grounded canonical metadata.
|
|
2. Maintain the established batch workflow: investigate 5 operations at a time, update registrars, regenerate CE/EE specs, validate, update progress, commit/push periodically.
|
|
3. Document for each operation:
|
|
- Summary and detailed description.
|
|
- Path/query/header/body schemas and required fields.
|
|
- Response schemas and status codes.
|
|
- Auth/security requirements.
|
|
- Tenant scoping and RBAC behavior.
|
|
- ID provenance and table/column origins where applicable.
|
|
- Known implementation gaps when source behavior differs from intended API behavior.
|
|
4. Keep generated specs synchronized:
|
|
- `sdk/docs/openapi/alga-openapi.ce.json`
|
|
- `sdk/docs/openapi/alga-openapi.ce.yaml`
|
|
- `sdk/docs/openapi/alga-openapi.ee.json`
|
|
- `sdk/docs/openapi/alga-openapi.ee.yaml`
|
|
- `sdk/docs/openapi/alga-openapi.json`
|
|
- `sdk/docs/openapi/alga-openapi.yaml`
|
|
5. Preserve existing local-only user changes, especially `.env.localtest`.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not fix runtime route bugs discovered during documentation, unless separately requested.
|
|
- Do not redesign auth, RBAC, or response envelopes.
|
|
- Do not convert all controllers to a new API framework.
|
|
- Do not create exhaustive endpoint-level integration tests for every route as part of this documentation pass.
|
|
- Do not modify `.env.localtest`.
|
|
|
|
## Target Users / Personas
|
|
|
|
- External API integrators using OpenAPI docs or generated SDKs.
|
|
- Alga engineers maintaining API controllers and route registrars.
|
|
- AI/chat/tool-call systems consuming API registry metadata.
|
|
- QA/release engineers validating that API docs match implemented behavior.
|
|
|
|
## Primary Workflow
|
|
|
|
1. Select next 5 unresolved placeholders from `sdk/docs/openapi/alga-openapi.ce.json`.
|
|
2. Launch 5 parallel investigator subagents with model `deepseek/deepseek-v4-pro` when available.
|
|
3. Investigator reports must be read-only and include route behavior, auth, params/body, responses, ID provenance, and source evidence.
|
|
4. Writer updates or creates route registrar files under `server/src/lib/api/openapi/routes/`.
|
|
5. Import any new registrar in `server/src/lib/api/openapi/index.ts` before inventory backfill.
|
|
6. Regenerate specs:
|
|
- `npm --prefix sdk run openapi:generate`
|
|
- `npm --prefix sdk run openapi:generate -- --edition ee`
|
|
7. Validate selected operations no longer contain placeholder descriptions or `x-placeholder` metadata.
|
|
8. Update `/tmp/alga-openapi-doc-progress.md` and this plan as needed.
|
|
9. Commit/push registrar and generated spec changes, excluding `.env.localtest`.
|
|
|
|
## Current Baseline
|
|
|
|
- Branch: `docs/api-docs-input-output`
|
|
- Worktree: `/Users/roberisaacs/alga-psa.worktrees/docs/api-docs-input-output`
|
|
- Last completed batch: Batch 16
|
|
- Latest pushed commit at plan creation: `e733631bf docs(openapi): document asset history and automation execution routes`
|
|
- Remaining CE placeholder count: 488
|
|
- Next selected batch: Batch 17
|
|
|
|
Batch 17:
|
|
1. `GET /api/v1/automation/performance`
|
|
2. `GET /api/v1/automation/rules`
|
|
3. `POST /api/v1/automation/rules`
|
|
4. `POST /api/v1/automation/rules/bulk-execute`
|
|
5. `POST /api/v1/automation/rules/bulk-status`
|
|
|
|
## Data Model / API Integration Notes
|
|
|
|
- Manual registrars override inventory backfill because they are registered before `registerInventoryBackfillRoutes`.
|
|
- Existing route registrars can use local Zod schemas or imported API schemas where reliable.
|
|
- Generated inventory placeholders are detected by either:
|
|
- Description containing `generated automatically`, or
|
|
- `extensions.x-placeholder` in generated OpenAPI.
|
|
- CE placeholder count is the primary cursor because CE contains the shared baseline; EE generation must still be validated.
|
|
- Some route inventory entries may point to missing route files. Document these as inventory-only/missing-handler routes rather than inventing behavior.
|
|
|
|
## Risks and Constraints
|
|
|
|
- Many controllers have current implementation gaps, especially old `/api/v1` routes with missing request context wiring. Document actual behavior and intended behavior clearly.
|
|
- Some existing schemas do not match actual controller output. Prefer actual source behavior over aspirational schemas.
|
|
- Generated OpenAPI diffs are large; keep commits batch-oriented and descriptive.
|
|
- DeepSeek/OpenRouter availability can fluctuate. If subagents fail, document the failure in scratchpad/progress and continue with local source investigation only if necessary.
|
|
- Do not stage or commit `.env.localtest`.
|
|
|
|
## Acceptance Criteria / Definition of Done
|
|
|
|
The remaining OpenAPI documentation work is complete when:
|
|
|
|
1. CE generated spec has zero operations with placeholder descriptions or `x-placeholder` metadata.
|
|
2. EE generated spec has zero operations with placeholder descriptions or `x-placeholder` metadata, except intentional EE-only omissions if justified in scratchpad.
|
|
3. Every formerly-placeholder route has source-grounded metadata for inputs, outputs, auth, tenant behavior, and relevant status codes.
|
|
4. All new route registrar files are imported in `server/src/lib/api/openapi/index.ts` before inventory backfill.
|
|
5. `npm --prefix sdk run openapi:generate` succeeds.
|
|
6. `npm --prefix sdk run openapi:generate -- --edition ee` succeeds.
|
|
7. `/tmp/alga-openapi-doc-progress.md` is current.
|
|
8. This plan's `features.json` and `tests.json` are updated to reflect completion.
|
|
9. Changes are committed and pushed, with `.env.localtest` left untouched.
|
|
|
|
## Open Questions
|
|
|
|
- Should discovered runtime defects be filed separately as issues, or only documented in OpenAPI descriptions/extensions?
|
|
- Should the final pass include a generated report of all route implementation gaps found during documentation?
|
|
- Should generated OpenAPI operation IDs be normalized across all newly documented routes, or left omitted unless already established?
|