docs: design KYC bulk import workflow (Closes #58)

[playmaker410]

Summary

Resolves #58 — Add admin compliance bulk import design.

This PR delivers the full design specification for the KYC whitelist bulk import workflow. No upload UI, parser, or signing endpoint is implemented — this is a documentation and type-contract task only, per the issue requirements.

---

Deliverables

docs/kyc-bulk-import-design.md

Full end-to-end workflow spec covering:

• 10-step sequence diagram with the human review gate explicitly marked before any state change is committed (maker-checker enforced)
• CSV format spec: 9 columns, required vs optional, UTF-8/comma encoding, versioning strategy for future schema changes without breaking old templates
• 15 validation rules: 10 schema-level hard rejects (S-001→S-010) + 5 data-level hard rejects (D-001→D-005) + 7 soft warnings (W-001→W-007), each with justification for its classification
• Preview rules: per-row diff layout, aggregate summary format, read-only/non-committing constraints
• Maker-checker section: self-whitelisting block (D-004), three signing mechanism options flagged as open questions rather than assumed
• Error handling: hard errors block whole batch; partial-apply failure policy with partially_applied status
• Security risks: self-whitelisting, privilege escalation, replay attack, compromised uploader, RBAC matrix, rate limits, immutable audit trail schema
• 6 open questions for team confirmation before implementation

docs/kyc-bulk-import-template.csv

Sample template with:

• 1 valid approve row
• 1 valid flag-for-review row
• 1 intentionally invalid row (INVALID_ADDRESS_FORMAT) illustrating rules D-001/W-001/W-004

src/features/compliance/bulkImport.types.ts

TypeScript interfaces only (no functions, no API calls, no state logic):

• RawCsvRow — raw parsed CSV shape (all strings, pre-validation)
• ValidatedCsvRow — post-validation shape with coerced types + warnings
• BatchPreviewRow / BatchPreview / BatchPreviewSummary — diff shape (current → proposed per row)
• BatchStatus — full lifecycle: draft | pending_review | approved | rejected | applying | applied | partially_applied | expired | failed
• KycBatchRecord — persisted batch record
• ValidationFinding / ValidationWarning / ValidationError / ValidationResult
• HardRejectRuleId / SoftWarningRuleId — all rule IDs as typed unions
• KycBatchAuditRecord / AuditRowEntry — immutable audit log shape

src/components/README-bulk-import-notes.md

Review UI notes (not a component implementation):

• Preview table column spec matched to BatchPreviewRow fields
• Approve/reject button disable conditions (hard errors, self-approval block, wrong batch status)
• WCAG AA accessibility requirements for large-diff tables (keyboard nav, aria-rowcount, live regions, contrast)

---

Acceptance Criteria

• Bulk import design is documented
• CSV or template format is specified
• Validation and preview rules are included
• Review-before-signing is required
• Error handling is defined
• Security risks are documented

---

What was intentionally NOT built

• Upload UI component
• CSV parser logic
• Signing endpoint
• Any code path that commits changes without a review step

All signing mechanism options are flagged as open questions (OQ-02) for the team to confirm before implementation begins.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@Justine-Ifedozie's PR #186 was approved and merged by @El-swaggerito.

🏆 @Justine-Ifedozie: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (258 total points). Track your full progress on GrantFox.

👏 Great work, @Justine-Ifedozie! Keep contributing to Axionvera.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@GideonBature's PR #187 was approved and merged by @El-swaggerito.

🏆 @GideonBature: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (519 total points). Track your full progress on GrantFox.

👏 Great work, @GideonBature! Keep contributing to Axionvera.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@Justine-Ifedozie's PR #190 was approved and merged by @El-swaggerito.

🏆 @Justine-Ifedozie: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (363 total points). Track your full progress on GrantFox.

👏 Great work, @Justine-Ifedozie! Keep contributing to Axionvera.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@Justine-Ifedozie's PR #193 was approved and merged by @El-swaggerito.

🏆 @Justine-Ifedozie: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (468 total points). Track your full progress on GrantFox.

👏 Great work, @Justine-Ifedozie! Keep contributing to Axionvera.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@Justine-Ifedozie's PR #201 was approved and merged by @El-swaggerito.

🏆 @Justine-Ifedozie: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (503 total points). Track your full progress on GrantFox.

👏 Great work, @Justine-Ifedozie! Keep contributing to Axionvera.