69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# Feature Integration Playbook
|
|
|
|
Use this playbook when adding a feature to the boilerplate or adapting a proprietary feature from another product.
|
|
|
|
## Goal
|
|
|
|
Make the feature understandable before implementation. A human operator and a coding agent should be able to answer where the feature lives, who owns its configuration, which flows it exposes, and how to verify it.
|
|
|
|
## Required Steps
|
|
|
|
1. Read `docs/agent-entrypoints.md`.
|
|
2. Find or create a manifest in `docs/feature-manifests/`.
|
|
3. Classify ownership:
|
|
- `tenant-owned`: tenant configures and uses it.
|
|
- `admin-managed`: admin/platform configures it; tenant only uses approved surfaces.
|
|
- `hybrid`: admin defines policy/defaults; tenant can configure local behavior.
|
|
- `system-only`: internal platform feature with no tenant-owned controls.
|
|
4. Map surfaces:
|
|
- Admin route source files and canonical admin-host runtime paths.
|
|
- Tenant route source files and canonical tenant-host runtime paths.
|
|
- Public route source files and root/web-host runtime paths.
|
|
- API route source files and canonical API-host `/v1/...` runtime paths.
|
|
- Link/form/action helpers: `adminPath`, `appPath`, `apiPath`, cross-host helpers, or `UrlUtils.getModulePath(...)` for tenant modules.
|
|
5. Map persistence:
|
|
- Prisma models.
|
|
- Existing tables reused.
|
|
- Migrations required.
|
|
- Tenant scoping fields.
|
|
6. Map configuration:
|
|
- Admin settings.
|
|
- Tenant settings.
|
|
- Environment variables.
|
|
- Secrets and their owner.
|
|
7. Map runtime:
|
|
- Request/response only.
|
|
- Queue-backed.
|
|
- Worker-backed.
|
|
- Browser-backed.
|
|
8. Map controls:
|
|
- Permissions.
|
|
- Audit events.
|
|
- Billing or usage limits.
|
|
9. Define UAT:
|
|
- Operator-visible checks.
|
|
- Negative checks for forbidden access.
|
|
- Secret exposure checks if providers are involved.
|
|
|
|
## Implementation Rules
|
|
|
|
- Do not expose provider secrets through tenant loaders, API responses, client bundles or logs.
|
|
- Do not add sidebar/nav entries without stable UI IDs.
|
|
- Do not add new root UI primitives without updating `docs/ui-inventory/components.json`.
|
|
- Do not add worker behavior without declaring queues and jobs in the manifest.
|
|
- Do not add admin-managed tenant behavior without admin permissions and audit events.
|
|
- Keep proprietary feature logic behind explicit module boundaries.
|
|
- Do not hard-code legacy runtime paths such as `/admin/...`, `/app/...`, or `/api/v1/...` outside tests that explicitly cover legacy redirects.
|
|
- Do not ship visible UI text without locale keys and `pnpm run verify:i18n`.
|
|
|
|
## Done Criteria
|
|
|
|
- Manifest updated and valid.
|
|
- Routes and surfaces match the manifest.
|
|
- Permissions are enforced on admin/API/tenant surfaces.
|
|
- Tenant-scope negative tests cover forbidden reads and mutations.
|
|
- Route helpers and runtime host ownership are tested for new navigation.
|
|
- i18n and deploy/static verifiers relevant to the change have run.
|
|
- Required worker queues/jobs exist or are explicitly deferred.
|
|
- UAT checks pass or are marked as deferred with a reason.
|