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/seed-version-manifest.md
+++ b/docs/setup/seed-version-manifest.md
@@ -0,0 +1,136 @@
+# Seed Version and Manifest Strategy
+
+Seed manifests make setup repeatable, auditable, and safe to resume.
+
+## Seed Package Model
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Stable package name, such as `system-core`, `crm-foundation`, `crm-demo-uat`. |
+| `version` | Semantic version for the seed package. |
+| `type` | `foundation`, `organization`, `business`, `demo_uat`, or `setup_state`. |
+| `dependencies` | Package names and compatible versions required before this package. |
+| `checksum` | Checksum over manifest content and referenced item checksums. |
+| `appliedAt` | Timestamp when applied. |
+| `appliedBy` | User id or setup actor id. |
+| `targetOrganization` | Organization id/code when organization-scoped. |
+| `source` | `script`, `wizard`, `csv`, or `plugin`. |
+| `status` | `pending`, `applied`, `skipped`, `warning`, `failed`, `rolled_back`. |
+| `report` | Import/seed report with counts, warnings, errors, and storage compensation notes. |
+
+## Manifest Format
+
+```json
+{
+  "name": "crm-foundation",
+  "version": "1.0.0",
+  "type": "foundation",
+  "dependencies": ["system-core@1.0.0"],
+  "targetOrganization": "ALLA",
+  "source": "wizard",
+  "items": [
+    {
+      "file": "master-options.csv",
+      "checksum": "sha256:...",
+      "required": true,
+      "importOrder": "06"
+    },
+    {
+      "file": "document-sequences.csv",
+      "checksum": "sha256:...",
+      "required": true,
+      "importOrder": "14"
+    }
+  ]
+}
+```
+
+## Package Naming
+
+| Package | Type | Owner |
+| --- | --- | --- |
+| `system-core` | organization | setup foundation |
+| `crm-foundation` | foundation | foundation seed services |
+| `crm-organization` | organization | setup wizard/import |
+| `crm-business-import` | business | CSV import engine |
+| `crm-demo-uat` | demo_uat | UAT seed services |
+| `document-template-foundation` | foundation | document-template/PDF foundations |
+| `notification-foundation` | foundation | notification foundation |
+| `report-foundation` | foundation | CRM report foundation |
+
+## Version Rules
+
+| Existing Manifest | Incoming Manifest | Behavior |
+| --- | --- | --- |
+| none | any valid version | Apply when dependencies pass. |
+| same version + same checksum | same content | Skip and report already applied. |
+| same version + changed checksum | changed content | Warn/block unless `force` is true and package allows mutable same-version seed. |
+| older version | newer compatible version | Apply upgrade path after compatibility check. |
+| newer version | older version | Block unless explicit rollback mode exists. |
+| failed | same checksum | Allow retry from failed item when service is idempotent. |
+| rolled back | newer version | Apply only after dependency and cleanup verification. |
+
+## Checksum Rules
+
+- Item checksum uses canonical CSV bytes after line-ending normalization.
+- Manifest checksum includes sorted item checksums and manifest metadata except `appliedAt`, `appliedBy`, and runtime report.
+- Generated wizard inputs should be serialized into canonical JSON and hashed as an item, for example `wizard-organization.json`.
+- Storage object checksums should be recorded separately because storage writes cannot be DB-transactional.
+
+## Dependency Rules
+
+- Dependencies use package names and semver ranges, such as `crm-foundation@^1.0.0`.
+- A dependency is satisfied when a successful manifest with compatible version/checksum exists for the same target organization or global scope.
+- Missing required dependencies block apply.
+- Optional dependencies produce warnings.
+
+## Report Contract
+
+Every seed package apply should produce:
+
+```json
+{
+  "imported": 0,
+  "updated": 0,
+  "skipped": 0,
+  "errors": [],
+  "warnings": [],
+  "storage": {
+    "createdObjects": [],
+    "cleanupWarnings": []
+  }
+}
+```
+
+## Persistence Strategy
+
+Use proposed tables:
+
+- `seed_manifests`
+- `seed_manifest_items`
+
+D.7.1 does not add migrations. D.7.8 should implement persistence after setup APIs and CSV import behavior are stable.
+
+## Upgrade Behavior
+
+1. Resolve target organization.
+2. Load existing manifests for target scope.
+3. Validate package dependencies.
+4. Compute incoming checksums.
+5. Compare version/checksum behavior table.
+6. Dry-run item operations.
+7. Apply in import order.
+8. Store manifest and item reports in the same DB transaction where possible.
+9. Store storage compensation report after non-transactional storage operations.
+
+## Rollback Behavior
+
+Rollback is not a default seed feature. It requires:
+
+- previous manifest item reports
+- reversible upsert strategy
+- explicit reset scope
+- storage cleanup strategy
+- audit trail
+
+Until implemented, use scoped reset/reseed rather than pretending arbitrary rollback is safe.