task-d.7.2

2026-07-02 13:42:09 +07:00
parent bca8d3f7e0
commit 0ae4ae3e38
22 changed files with 4423 additions and 0 deletions
--- a/docs/setup/setup-plugin-architecture.md
+++ b/docs/setup/setup-plugin-architecture.md
@@ -0,0 +1,161 @@
+# 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.