162 lines
4.8 KiB
Markdown
162 lines
4.8 KiB
Markdown
# Setup Plugin Architecture
|
|
|
|
Goal: future modules can register setup behavior without editing the core wizard for every feature.
|
|
|
|
This is a design proposal only. No plugin runtime is implemented in D.7.1.
|
|
|
|
## Plugin Contract
|
|
|
|
```ts
|
|
interface SetupPlugin {
|
|
moduleId: string;
|
|
displayName: string;
|
|
dependencies: string[];
|
|
enabledCondition: SetupEnabledCondition;
|
|
setupSteps: SetupStepDefinition[];
|
|
csvTemplates: CsvTemplateDefinition[];
|
|
seedTasks: SeedTaskDefinition[];
|
|
verificationChecks: VerificationCheckDefinition[];
|
|
resetScopes: ResetScopeDefinition[];
|
|
}
|
|
```
|
|
|
|
## Fields
|
|
|
|
| Field | Purpose |
|
|
| --- | --- |
|
|
| `moduleId` | Stable identifier, for example `crm.quotation`. |
|
|
| `displayName` | Human-readable module name in setup UI. |
|
|
| `dependencies` | Other module ids or seed package versions required first. |
|
|
| `enabledCondition` | Function/config deciding if module applies to this installation. |
|
|
| `setupSteps` | Optional wizard steps or sections contributed by the module. |
|
|
| `csvTemplates` | CSV templates owned by the module. |
|
|
| `seedTasks` | Idempotent seed operations. |
|
|
| `verificationChecks` | Checks added to the verification matrix. |
|
|
| `resetScopes` | Reset/reseed behavior owned by the module. |
|
|
|
|
## Example Plugin Manifest
|
|
|
|
```json
|
|
{
|
|
"moduleId": "crm.quotation",
|
|
"displayName": "CRM Quotation",
|
|
"dependencies": ["core.foundation", "crm.foundation", "crm.approval"],
|
|
"setupSteps": ["document-sequences", "approval-workflow", "csv-import"],
|
|
"csvTemplates": ["quotations.csv", "quotation-items.csv", "quotation-parties.csv"],
|
|
"seedTasks": ["quotation-document-sequences", "quotation-template-mappings"],
|
|
"verificationChecks": ["SEQUENCE_QUOTATION", "APPROVAL_WORKFLOW", "PDF_TEMPLATE_ASSET"],
|
|
"resetScopes": ["business_reset", "demo_uat_reset"]
|
|
}
|
|
```
|
|
|
|
## Core Modules
|
|
|
|
| Module | Owns |
|
|
| --- | --- |
|
|
| `core.foundation` | Readiness, users, organizations, memberships, setup state, seed manifests. |
|
|
| `crm.foundation` | Master options, branch/product type scopes, CRM role profiles, CRM assignments. |
|
|
| `crm.customer` | Customers, contacts, contact sharing, customer ownership verification. |
|
|
| `crm.lead` | Lead import, lead sequence verification, lead master options. |
|
|
| `crm.opportunity` | Opportunity import, parties, followups, outcome lifecycle checks. |
|
|
| `crm.quotation` | Quotations, items, parties, topics, quotation sequences. |
|
|
| `crm.approval` | Workflows, steps, matrices, approval verification. |
|
|
| `document` | Templates, template versions, mappings, libraries. |
|
|
| `notification` | Notification templates and provider readiness checks. |
|
|
| `reporting` | Report definitions and report catalog verification. |
|
|
| `future_asset` | Placeholder for asset/warehouse/catalog setup after schema decisions. |
|
|
| `future_hr` | Placeholder for teams/departments after schema decisions. |
|
|
|
|
## Execution Order
|
|
|
|
1. Load core plugins.
|
|
2. Resolve enabled modules.
|
|
3. Build dependency graph.
|
|
4. Detect cycles.
|
|
5. Sort setup steps by dependency and declared order.
|
|
6. Merge CSV templates and reject duplicate file ownership.
|
|
7. Merge verification checks and reset scopes.
|
|
8. Render wizard steps by module and step group.
|
|
|
|
## Cycle Rules
|
|
|
|
- A plugin cannot depend on itself.
|
|
- Cycles block setup startup with a developer-facing error.
|
|
- Optional dependencies must not introduce ordering ambiguity.
|
|
|
|
## Extension Points
|
|
|
|
### Setup Step
|
|
|
|
```ts
|
|
interface SetupStepDefinition {
|
|
key: string;
|
|
title: string;
|
|
required: boolean;
|
|
inputsSchema: unknown;
|
|
previewAction?: string;
|
|
commitAction?: string;
|
|
produces: string[];
|
|
invalidates: string[];
|
|
}
|
|
```
|
|
|
|
### CSV Template
|
|
|
|
```ts
|
|
interface CsvTemplateDefinition {
|
|
fileName: string;
|
|
requiredColumns: string[];
|
|
optionalColumns: string[];
|
|
importOrder: string;
|
|
targetService: string;
|
|
unsupportedReason?: string;
|
|
}
|
|
```
|
|
|
|
### Seed Task
|
|
|
|
```ts
|
|
interface SeedTaskDefinition {
|
|
key: string;
|
|
packageName: string;
|
|
version: string;
|
|
idempotent: boolean;
|
|
dependencies: string[];
|
|
dryRunAction: string;
|
|
commitAction: string;
|
|
}
|
|
```
|
|
|
|
### Verification Check
|
|
|
|
```ts
|
|
interface VerificationCheckDefinition {
|
|
checkId: string;
|
|
area: string;
|
|
requiredFor: string[];
|
|
runAction: string;
|
|
suggestedFix: string;
|
|
}
|
|
```
|
|
|
|
### Reset Scope
|
|
|
|
```ts
|
|
interface ResetScopeDefinition {
|
|
key: string;
|
|
destructive: boolean;
|
|
allowedEnvironments: string[];
|
|
requiresTypedConfirmation: boolean;
|
|
affectedTables: string[];
|
|
storageCleanup: "none" | "report_only" | "best_effort";
|
|
}
|
|
```
|
|
|
|
## Safety Rules
|
|
|
|
- Plugins can register behavior but cannot bypass setup core authorization.
|
|
- Plugin seed tasks must be idempotent or marked unsafe.
|
|
- Plugin reset scopes must declare affected tables and storage behavior.
|
|
- Plugin CSV templates must declare ownership to avoid two modules writing the same file contract.
|
|
- Setup core owns persistence of run state, manifests, audit events, and final reports.
|