# NexusCRM Final Assessment — Design Gaps, Progress Bottlenecks, Critical Missing Features **Date**: 2026-03-31 **Method**: 5 specialized agents (Design, Bottlenecks, Features, SF Parity, Synthesis) cross-referencing v1/v2/challenge analysis + live code verification --- ## I. Salesforce Parity Scorecard | # | Platform Capability | Rating | Key Gap | |---|---|---|---| | 1 | Metadata-Driven Rendering | **YELLOW** | Architecture sound; curated layouts are dead code, all objects auto-generated | | 2 | RecordType + PageLayout Matrix | **RED** | All RTs map to same layout; no (Profile, RT) -> Layout matrix | | 3 | Validation Framework | **YELLOW** | ~30 SF functions implemented; 18 missing; unsupported rules silently skipped | | 4 | SOQL Completeness | **YELLOW** | Subqueries + aggregates present; GROUP BY single-field only; no TYPEOF/semi-joins | | 5 | Sharing Model | **YELLOW** | 5-layer record access + role hierarchy; OWD not enforced at query time | | 6 | Workflow Automation (Flow) | **GREEN** | Decision/Loop/RecordOps/Triggers/Subflow/Scheduling all working | | 7 | Multi-Currency | **RED** | No CurrencyIsoCode, no CurrencyType, hardcoded `$` formatting | **Bottom line**: 1 GREEN, 4 YELLOW, 2 RED. Platform can serve as a single-currency basic CRUD CRM today, but cannot replace Salesforce for orgs needing RecordType-specific layouts or multi-currency. --- ## II. Design-Level Problems (设计层面) These are structural decisions that will keep generating new issues indefinitely. ### Design Gap 1: No Metadata Semantic Quality Gate **The gap**: Bootstrap has structural assertions (table exists, column exists) at `assertions_metadata.go` but ZERO semantic checks. No validation that: - Field labels are human-readable (not raw API names) - Standard objects have curated layouts - Picklist fields have defined values - Validation rule formulas reference existing fields **Evidence**: `backend/internal/bootstrap/assertions_metadata.go` — 5 structural checks, 0 semantic checks. All run at `main.go:215`. **Blast radius**: ~70 existing issues + 5-10 new issues per quarter. Every new object/field auto-discovered will reproduce the same label/layout/picklist defects. **Fix**: Add `assertMetadataSemanticQuality()` to the existing assertions framework. ~150 lines in a new file. Warnings initially, errors once gaps are fixed. **Effort: M** ### Design Gap 2: SuperUser Bypass Ignores Field Intrinsic Editability **The gap**: `CheckFieldEditabilityWithUser` at `permissions/service.go:152-153` returns `true` for ALL non-system fields when user is admin. AutoNumber, Formula, and Calculated fields appear as `updateable=true` in describe. Frontend correctly trusts this and includes them in PATCH payloads. Backend SchemaValidator then rejects. **Evidence**: `service.go:140-153` — SuperUser check before intrinsic-editability check. `IsFieldSystemReadOnly` only covers 6 hardcoded system fields, not computed business fields. **Blast radius**: ~10 existing issues. Every new AutoNumber/Formula field on any object will reproduce for admin users. Currently blocks Quote editing (P0). **Fix**: Insert `isFieldIntrinsicallyReadOnly` check (AutoNumber/Formula/Calculated) BEFORE the SuperUser bypass. 3 lines. **Effort: S** ### Design Gap 3: Layout Lifecycle Has No Curated Seed Path **The gap**: `standard_layouts.json` has 9 curated Salesforce-parity layouts — it is dead code (no loader). `CleanupHardcodedLayouts` at `layouts.go:42-53` actively DELETES seeded layouts on every startup. 100% of objects fall to Tier 3 auto-generation. **Why it was removed**: Old seed layouts had only 8-27 standard fields, hiding 200+ custom fields. The deletion was intentional. **Evidence**: Zero `//go:embed` or file read for `standard_layouts.json`. `CleanupHardcodedLayouts` called at `main.go:157`. **Blast radius**: 32 existing issues. Every new standard object will also get generic auto-generated layouts. **Fix**: Load JSON as section TEMPLATES, merge with live schema fields, set `IsCustomized=1`. ~80 lines. Remove `CleanupHardcodedLayouts`. **Effort: M** ### Design Gap 4: "Frontend = Specification" Axiom Has No Enforcement **The gap**: The project's core correctness axiom exists only as documentation in CLAUDE.md. No automated contract test validates backend responses match Salesforce wire format. Frontend types use `?` optional fields that silently tolerate missing data rather than failing fast. **Evidence**: `tests/contract/` contains only markdown scenarios and Chrome exploration docs. No Go or TypeScript schema validators. Frontend `schemas.ts:141` has `label || humanizeFieldName()` fallback that masks backend bugs. **Blast radius**: ~15 compatibility regressions per quarter, caught only by manual testing. The axiom erodes over time. **Fix**: Build contract test suite with Salesforce golden fixtures vs NexusCRM responses. Run in CI. **Effort: L** --- ## III. Progress Bottlenecks (当前推进瓶颈) These are blocking the team from shipping RIGHT NOW. ### Bottleneck 1: CI Is Permanently Red on Main **What**: 10/10 recent CI runs on main have failed. Integration tests fail (2 layout-related tests), frontend tests fail (7 tests in `ApprovalProcessDetailPage.test.tsx` due to incomplete `useSchema` mock). Meanwhile, deploy.yml succeeds on all 10 pushes because it has no `needs:` dependency on CI. **What it blocks**: EVERYTHING. No fix can be verified. Developers cannot distinguish "my change broke something" from "already broken." The 40 testing-related issues stem from this: when CI is red, writing new tests feels futile. **Unblock**: Fix 9 failing tests (mock fix + layout test fixtures). Gate deploy on CI. **Effort: S (1-2 days)** ### Bottleneck 2: 35 P0 Issues Create Decision Paralysis **What**: 35 issues labeled P0 (verified via `gh issue list`). When everything is top priority, nothing is. v1 listed 11, v2 challenge reframed to 66 "missing features." The actual P0 label count is even higher. **What it blocks**: Developer focus. Work scatters across 35 "top priority" items and none gets finished. **Unblock**: Triage P0s into "actually blocks a user workflow" vs "mislabeled." Pick ONE object (Lead or Account) and make its full workflow work end-to-end. Use that as the template. **Effort: S for triage (1 day), L for one-object completion (2-3 weeks)** ### Bottleneck 3: Bootstrap Has No Migration Framework **What**: 26 serial bootstrap steps in `main.go:68-220` with no versioned migration tracking. Data changes are embedded in Go code and re-applied every boot. `CleanupSystemListFields` called TWICE (lines 162 and 170). `EnsureStandardIndexes` runs async with no sync point before assertions. **What it blocks**: Environment parity (dev/staging/prod drift). Admin customizations overwritten on restart. No way to selectively apply a data change. **Unblock**: Short-term: add `IsCustomized` guards to destructive bootstrap ops. Medium-term: migration table with version tracking. **Effort: M (1 week)** --- ## IV. Critical Missing Features (关键功能缺失) Features where the frontend expects them but the backend doesn't deliver, making core CRM workflows unusable. ### Feature 1: Lead Conversion — Request Format Mismatch **Frontend**: `actions.ts:24` sends flat JSON `{ leadId, convertedStatus, ... }` **Backend**: `standard_actions_handler.go:51-57` requires `{ "inputs": [{ ... }] }` **Result**: Guaranteed 400 error on every conversion attempt. **User impact**: Sales pipeline completely broken — leads cannot progress. **Fix**: Frontend wraps payload in `inputs[]` array. 5 lines. **Effort: S** ### Feature 2: Activity Tab — Placeholder Only **Frontend**: `MetadataRecordDetail.tsx:457-471` renders Activity tab. `ActivityFeed.tsx` only shows Comments + AuditLog. `RecordTabs.tsx:31-38` has a hardcoded placeholder "Feed for record {recordId}". **Backend**: Task and Event objects exist but are not queried for activity timeline. **Result**: No engagement tracking. Users cannot see/log calls, meetings, tasks, emails. **User impact**: CRM is a data entry tool, not an engagement tracker. **Fix**: Add Task/Event SOQL queries to ActivityFeed + wire tab registration. ~200 lines. **Effort: M** ### Feature 3: Search Suggestions — No Backend Route **Frontend**: `GlobalSearch.tsx:122-123` calls `searchSuggestions(term)` on every keystroke. **Backend**: No `/search/suggestions` route in `routes.go`. Returns 404. **Result**: Typeahead never populates. Search feels slow. **Fix**: Add suggestions handler using existing parameterized search. ~50 lines. **Effort: M** ### Feature 4: Quote Edit Blocked for Admins **Frontend**: Trusts `updateable` from describe, includes AutoNumber in PATCH. **Backend**: SuperUser bypass makes AutoNumber `updateable=true`. SchemaValidator rejects. **Result**: Admin users cannot edit Quotes. P0. **Fix**: 3-line permission fix (Design Gap #2). **Effort: S** ### Feature 5: Error Feedback on 400 Responses **Frontend**: No error toast shown when save/create returns HTTP 400. Users see nothing. **Backend**: Returns Salesforce-format errors with `errorCode` + `message`, but not always user-friendly. **Result**: Every failed operation is silent. Users cannot diagnose or recover. **Fix**: Global error interceptor in API client + message sanitization. ~30 lines. **Effort: S** ### Feature 6: File Attachment — Not Linked to Records **Frontend**: `filesAPI.upload()` POSTs to `/sobjects/ContentVersion`. **Backend**: Files saved to disk with UUID. No `ContentDocumentLink` junction object. **Result**: Files exist standalone. Cannot attach to records. Files related list is empty. **Fix**: Add ContentDocumentLink table + create on upload. ~100 lines. **Effort: M** ### Feature 7: Approval Actions Not Executed **Frontend**: `ProcessActionsSection.tsx` creates FieldUpdate/EmailAlert action configs. **Backend**: `ApprovalService` handles Submit/Approve/Reject/Recall state transitions but does NOT execute configured actions (field updates, email alerts) when transitions happen. **Result**: Approval is manual-only. No automated side effects on approval. **Fix**: Wire action execution in approval state transitions. ~80 lines. **Effort: M** ### Feature 8: RecordType-to-Layout Differentiation **Backend**: `sobject_describe.go:330` hardcodes `layoutID = fmt.Sprintf("%s-default-layout", objectName)` for ALL record types. **Result**: Different record types (e.g., "New Business" vs "Renewal" Opportunity) show identical forms. **Fix**: Add RecordType dimension to layout resolution. ~50 lines. **Effort: M** --- ## V. Recommended Execution Order ``` Week 1: STOP THE BLEEDING ├── Fix 9 failing tests on main (S, 1-2 days) ├── Gate deploy on CI (S, 30 min) ├── Fix SuperUser permission bypass — 3 lines (S, 1 day) ├── Fix Lead conversion request format — 5 lines (S, 1 day) └── Add error feedback on 400 responses — 30 lines (S, 1 day) Week 2-3: BUILD THE QUALITY GATE ├── Add metadata semantic quality assertions (M, 3 days) ├── Implement layout seed loader (merge templates + live schema) (M, 5 days) ├── Fix SaveLayout to auto-set IsCustomized (S, 1 day) └── Wire Activity tab (Task/Event queries + tab registration) (M, 3 days) Week 4-5: COMPLETE ONE OBJECT END-TO-END ├── Pick Lead or Account as reference object ├── Make full workflow work: create → edit → detail → list → convert/relate ├── Add search suggestions endpoint (M, 2 days) ├── Add related list system object filtering (S, 1 day) └── File attachment linking (ContentDocumentLink) (M, 3 days) Week 6+: SCALE THE PATTERN ├── Apply reference object pattern to remaining standard objects ├── Build contract test suite (SF golden fixtures vs NexusCRM) (L) ├── RecordType-to-Layout matrix (M) ├── Approval action execution (M) └── Migration framework (M) ``` ### What This Plan Does NOT Do (Explicitly Excluded) | Item | Why Excluded | |------|-------------| | Multi-currency | RED on scorecard but only matters for international deployments. Defer. | | ServiceManager refactoring | Correct observation, 100+ files to touch, low immediate ROI | | SOQL advanced features (TYPEOF, semi-joins) | YELLOW is acceptable for basic CRM | | Screen Flows | Flow engine is GREEN without them | | Dependent picklists | Nice-to-have for data quality, not a workflow blocker | | Bootstrap orchestrator refactor | Correct but medium effort for low recurrence rate | --- ## VI. The One-Sentence Summary **NexusCRM has a sound metadata-driven architecture (the hardest part), but is stuck in a "works in demo, breaks in workflow" state because: (1) curated layouts are dead code, (2) the permission model makes computed fields writable for admins, (3) CI is permanently red so nothing can be verified, and (4) five core CRM workflows (Lead conversion, Activity tracking, Quote editing, Search typeahead, File attachment) are broken or missing at the integration point between frontend and backend.** The fix is not a rewrite — it's ~500 lines of targeted changes across 15 files, plus a metadata quality gate to prevent recurrence.