137 lines
4.6 KiB
Markdown
137 lines
4.6 KiB
Markdown
# 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.
|