diff --git a/docs/NEXT-PHASE.md b/docs/NEXT-PHASE.md index ad1ba16..e265e1b 100644 --- a/docs/NEXT-PHASE.md +++ b/docs/NEXT-PHASE.md @@ -1,9 +1,9 @@ -# Next Development Phase — Roadmap to v1.0 GA +# Next Development Phase — Roadmap to v1.0 GA & Beyond -> **Date**: 2026-02-09 -> **Status**: All Feature Development & Testing Complete — Entering Final Validation +> **Date**: 2026-02-10 (Updated after `@objectstack/spec@2.0.4` gap analysis) +> **Status**: All Feature Development & Testing Complete — Entering Final Validation + Spec Alignment > **Test Status**: ✅ 493/493 tests passing (58 suites) -> **SDK**: `@objectstack/client@2.0.1` — all 13 API namespaces available +> **SDK**: `@objectstack/client@2.0.4`, `@objectstack/client-react@2.0.4`, `@objectstack/spec@2.0.4` --- @@ -37,6 +37,55 @@ All development phases (0 through 5B) and most of Phase 6 are **complete**: --- +## Spec v2.0.4 Gap Analysis Summary + +> `@objectstack/spec` is the protocol "constitution" for all ObjectStack development. +> The spec defines **15 modules**: root, driver, data, system, auth, kernel, hub, ai, automation, api, ui, contracts, integration, studio, permission. +> The mobile app must align with this protocol to remain specification-compliant. + +### Protocol Compliance Matrix + +| Spec Module | Client SDK | Mobile Status | Gap | +|-------------|-----------|---------------|-----| +| `spec/api` — CRUD, Metadata, Auth, Views | `client.data.*`, `client.meta.*`, `client.auth.*`, `client.views.*` | ✅ Fully implemented | — | +| `spec/api` — Permissions | `client.permissions.*` | ✅ `usePermissions` hook | — | +| `spec/api` — Workflow | `client.workflow.*` | ✅ `useWorkflowState` hook | — | +| `spec/api` — Realtime/WebSocket | `client.realtime.*` | ✅ `useSubscription` hook | — | +| `spec/api` — Notifications | `client.notifications.*` | ✅ `useNotifications` hook | — | +| `spec/api` — AI (NLQ, Chat, Suggest, Insights) | `client.ai.*` | ✅ `useAI` hook | — | +| `spec/api` — i18n | `client.i18n.*` | ✅ `useServerTranslations` hook | — | +| `spec/api` — Files | `client.files.*` | ✅ `useFileUpload` hook | — | +| `spec/api` — Analytics | `client.analytics.query/meta` | ✅ `useAnalyticsQuery/Meta` hooks | ⚠️ `analytics.explain()` not used | +| `spec/api` — Automation Triggers | `client.automation.trigger()` | ⚠️ Only in `ActionExecutor` | 🔴 No dedicated hook | +| `spec/api` — Package Management | `client.packages.*` (list/get/install/uninstall/enable/disable) | ⚠️ `useAppDiscovery` uses `list` only | 🔴 Install/uninstall/enable/disable not exposed | +| `spec/api` — Batch Data Operations | `client.data.batch/createMany/updateMany/deleteMany` | ✅ `useBatchMutation` hook | — | +| `spec/ui` — Report/Analytics Views | `ReportSchema`, `ReportChart`, `ReportColumn`, `ReportGrouping` | ❌ Not implemented | 🟡 New view type | +| `spec/ui` — Page/SDUI Composition | `PageSchema`, `PageComponent`, `PageRegion`, `PageVariable` | ❌ Not implemented | 🟡 Spec mandates SDUI | +| `spec/ui` — Widget System | `WidgetManifest`, `WidgetLifecycle`, `WidgetEvent`, `WidgetProperty` | ❌ Not implemented | 🟡 Extensibility layer | +| `spec/ui` — Theme Tokens | `ThemeSchema`, `ColorPalette`, `Typography`, `Spacing`, `Shadow` | ⚠️ NativeWind/Tailwind used | 🟢 Can map tokens | +| `spec/ai` — MCP Server Integration | `MCPServerConfig`, `MCPTool`, `MCPResource`, `MCPPrompt` | ❌ Not implemented | 🟡 AI extensibility | +| `spec/ai` — RAG Pipeline | `RAGPipelineConfig`, `RAGQueryRequest/Response` | ❌ Not implemented | 🟡 Advanced AI | +| `spec/ai` — Conversation Session | `ConversationSession`, `ConversationMessage`, `TokenBudget` | ⚠️ Basic in `useAI` | 🟡 Missing session persistence | +| `spec/ai` — Agent System | `AgentSchema`, `AgentAction`, `AgentActionSequence` | ❌ Not implemented | 🟡 Agent orchestration | +| `spec/ai` — Cost Management | `CostAnalytics`, `BudgetLimit`, `CostAlert` | ❌ Not implemented | 🟢 Admin feature | +| `spec/automation` — Flow Builder | `FlowSchema`, `FlowNode`, `FlowEdge`, `FlowVariable` | ❌ Not implemented | 🟡 Visual automation | +| `spec/automation` — ETL Pipelines | `ETLPipeline`, `ETLSource`, `ETLDestination` | ❌ Not implemented | 🟢 Admin feature | +| `spec/automation` — Approval Processes | `ApprovalProcess`, `ApprovalStep` | ❌ No mobile UI | 🔴 Needed for workflows | +| `spec/automation` — State Machine Config | `StateMachineConfig`, `StateNodeConfig`, `Transition` | ⚠️ Runtime state only | 🟡 Config viewing | +| `spec/system` — Collaboration/CRDT | `CollaborationSession`, `CRDTState`, `OTOperation` | ❌ Not implemented | 🟡 Real-time co-editing | +| `spec/system` — Audit Log | `AuditEvent`, `AuditConfig` | ❌ Not implemented | 🟢 Admin feature | +| `spec/integration` — Connectors | `ConnectorInstance`, `ConnectorOperation` | ❌ Not implemented | 🟢 Admin feature | +| `spec/kernel` — Plugin System | `PluginSchema`, `PluginCapability` | ❌ Not implemented | 🟢 Platform feature | +| `spec/studio` — Studio Plugins | `StudioPluginManifest`, `StudioPluginContributions` | ❌ Not applicable | — Desktop only | + +### Priority Legend + +- 🔴 **High** — Needed for core user workflows +- 🟡 **Medium** — Enhances spec compliance or user experience +- 🟢 **Low** — Admin/platform features, can defer to post-GA + +--- + ## Phase 7: Final Validation & Production Polish > **Goal**: Validate all implemented features end-to-end and ensure production-grade quality. @@ -152,6 +201,257 @@ All development phases (0 through 5B) and most of Phase 6 are **complete**: --- +## Phase 9: Spec v2.0.4 Alignment — Core Protocol Compliance + +> **Goal**: Close the highest-priority gaps identified in the spec analysis to ensure protocol compliance. +> +> **Duration**: 2–3 weeks +> +> **Prerequisites**: Phases 7–8 in progress or complete + +### 9.1 Automation Hook & Approval Process UI (Priority: 🔴 High) + +> The spec defines `automation` as a first-class module. The client exposes `client.automation.trigger()` but mobile only uses it inside `ActionExecutor`. Approval processes (`ApprovalProcess`, `ApprovalStep`) are defined in `spec/automation` and are critical for business workflow users on mobile. + +**Deliverables:** +- [ ] Create `hooks/useAutomation.ts` — dedicated hook wrapping `client.automation.trigger()` + - Expose `trigger(name, payload)`, `loading`, `error` state + - Support optimistic UI feedback +- [ ] Create `components/workflow/ApprovalCard.tsx` — inline approval UI + - Show pending approvals with approve/reject actions + - Integrate with `client.workflow.approve()` and `client.workflow.reject()` +- [ ] Create `components/workflow/ApprovalList.tsx` — list of pending approvals + - Filter by object, status, assigned approver +- [ ] Add approval count badge to tab bar / notification center +- [ ] Export `useAutomation` from `hooks/useObjectStack.ts` barrel +- [ ] Tests for `useAutomation` hook and approval components + +**Estimated Time**: 3–4 days + +### 9.2 Full Package Management (Priority: 🔴 High) + +> The client SDK exposes `client.packages.install/uninstall/enable/disable` but mobile only uses `client.packages.list()` in `useAppDiscovery`. Users need to manage extensions from mobile. + +**Deliverables:** +- [ ] Extend `hooks/useAppDiscovery.ts` or create `hooks/usePackageManagement.ts` + - `install(manifest, options?)` — install a new package + - `uninstall(id)` — uninstall a package + - `enable(id)` / `disable(id)` — toggle package status + - Loading/error states per operation +- [ ] Create `components/packages/PackageCard.tsx` — show package info with actions +- [ ] Create `components/packages/PackageList.tsx` — browsable package list with status filters +- [ ] Create screen route `app/(app)/packages.tsx` for package management +- [ ] Tests for package management hook + +**Estimated Time**: 2–3 days + +### 9.3 Analytics Explain & SQL (Priority: 🟡 Medium) + +> The client exposes `client.analytics.explain(payload)` for SQL explain plans. This is useful for power users debugging analytics queries. + +**Deliverables:** +- [ ] Extend `hooks/useAnalyticsQuery.ts` to expose `explain(payload)` method +- [ ] Show query explanation in analytics/chart detail views when in debug mode +- [ ] Tests for explain integration + +**Estimated Time**: 0.5 day + +--- + +## Phase 10: Spec v2.0.4 Alignment — UI Protocol Compliance + +> **Goal**: Implement spec-mandated UI patterns: SDUI page composition, report views, and theme token mapping. +> +> **Duration**: 2–3 weeks + +### 10.1 Report View Renderer (Priority: 🟡 Medium) + +> `spec/ui` defines `ReportSchema` with types: `tabular`, `summary`, `matrix`, `chart`. The mobile app has chart rendering but no dedicated report view that aggregates columns, groupings, and chart configurations. + +**Deliverables:** +- [ ] Create `components/renderers/ReportRenderer.tsx` + - Accept `ReportSchema` config (type, columns, groupings, chart) + - Render tabular reports with column definitions + - Render summary reports with aggregation rows + - Render matrix (pivot) reports + - Integrate with existing `ChartRenderer` for chart reports +- [ ] Wire into `ViewFactory` for `type: 'report'` +- [ ] Tests and snapshot tests for report renderer + +**Estimated Time**: 3–4 days + +### 10.2 SDUI Page Composition (Priority: 🟡 Medium) + +> Per `spec/ui`, pages should be **Server-Driven UI** composed from `PageSchema` → `PageRegion` → `PageComponent`. The mobile app currently uses file-based Expo Router pages. The spec mandates rendering dynamically from metadata. + +**Deliverables:** +- [ ] Create `lib/page-renderer.ts` — parse and validate `PageSchema` from API +- [ ] Create `components/renderers/PageRenderer.tsx` + - Render `PageRegion` (header, main, sidebar, footer) layouts + - Map `PageComponent` types to existing renderers (list, form, chart, dashboard widget, etc.) + - Support `PageVariable` bindings for dynamic data +- [ ] Create `app/(app)/page/[id].tsx` — dynamic SDUI route + - Fetch `PageSchema` from `client.meta.getView()` or a new page API + - Render using `PageRenderer` +- [ ] Tests for page renderer logic + +**Estimated Time**: 4–5 days + +### 10.3 Theme Token Mapping (Priority: 🟢 Low) + +> `spec/ui` defines `ThemeSchema` with tokens: `ColorPalette`, `Typography`, `Spacing`, `Shadow`, `BorderRadius`, `Breakpoints`, `ZIndex`. The mobile app uses NativeWind/Tailwind for styling. A bridge layer can map spec tokens to Tailwind config. + +**Deliverables:** +- [ ] Create `lib/theme-bridge.ts` — convert `ThemeSchema` tokens to Tailwind-compatible config + - Map `ColorPalette` → Tailwind `colors` + - Map `Typography` → Tailwind `fontFamily`/`fontSize` + - Map `Spacing` → Tailwind `spacing` +- [ ] Optionally allow server-driven theme overrides at runtime +- [ ] Tests for theme token mapping + +**Estimated Time**: 1–2 days + +### 10.4 Widget System Foundation (Priority: 🟢 Low) + +> `spec/ui` defines `WidgetManifest`, `WidgetLifecycle`, `WidgetEvent`, `WidgetProperty`, `WidgetSource` for an extensible widget framework. + +**Deliverables:** +- [ ] Create `lib/widget-registry.ts` — register and resolve widgets by manifest +- [ ] Create `components/widgets/WidgetHost.tsx` — render a widget from manifest +- [ ] Support lifecycle events (mount, unmount, update) +- [ ] Tests for widget registry + +**Estimated Time**: 2–3 days + +--- + +## Phase 11: Spec v2.0.4 Alignment — AI & Intelligence + +> **Goal**: Implement advanced AI protocol features: conversation persistence, RAG pipelines, MCP integration, and agent orchestration. +> +> **Duration**: 2–3 weeks + +### 11.1 Conversation Session Persistence (Priority: 🟡 Medium) + +> `spec/ai` defines `ConversationSession` with session management, message pruning, and token budget tracking. Current `useAI` hook has basic chat but no session persistence or token management. + +**Deliverables:** +- [ ] Extend `hooks/useAI.ts` to support: + - `createSession(context)` — create a named conversation session + - `resumeSession(sessionId)` — resume an existing session + - `sessionMessages` — persistent message history + - Token usage tracking (`TokenUsageStats`) + - Token budget enforcement (`TokenBudgetConfig`) +- [ ] Store conversation sessions in offline storage (SQLite) +- [ ] Add session list UI for switching between conversations +- [ ] Tests for session management + +**Estimated Time**: 3–4 days + +### 11.2 RAG Pipeline Integration (Priority: 🟡 Medium) + +> `spec/ai` defines `RAGPipelineConfig`, `RAGQueryRequest`, `RAGQueryResponse` for retrieval-augmented generation. This allows AI to search knowledge bases before generating responses. + +**Deliverables:** +- [ ] Create `hooks/useRAG.ts` + - `query(request: RAGQueryRequest)` → `RAGQueryResponse` + - Display source documents/citations in chat responses + - Show retrieval confidence scores +- [ ] Integrate RAG results into `useAI` chat flow +- [ ] Export from `hooks/useObjectStack.ts` +- [ ] Tests for RAG hook + +**Estimated Time**: 2–3 days + +### 11.3 MCP (Model Context Protocol) Awareness (Priority: 🟢 Low) + +> `spec/ai` defines full MCP schemas: `MCPServerConfig`, `MCPTool`, `MCPResource`, `MCPPrompt`. Mobile doesn't need to host MCP servers but should be aware of MCP-connected tools. + +**Deliverables:** +- [ ] Create `hooks/useMCPTools.ts` — discover and display MCP-connected tools + - List available tools from server MCP configuration + - Allow triggering MCP tools from mobile (via server proxy) +- [ ] Show MCP tool availability in AI chat interface +- [ ] Tests for MCP tools hook + +**Estimated Time**: 2 days + +### 11.4 Agent Orchestration UI (Priority: 🟢 Low) + +> `spec/ai` defines `AgentSchema`, `AgentAction`, `AgentActionSequence` for multi-step agent workflows. + +**Deliverables:** +- [ ] Create `hooks/useAgent.ts` — interact with server-side agents + - Start agent task, monitor progress, view results + - Support agent action sequences with step-by-step UI +- [ ] Create `components/ai/AgentProgress.tsx` — visualize agent execution +- [ ] Tests for agent hook + +**Estimated Time**: 3–4 days + +--- + +## Phase 12: Spec v2.0.4 Alignment — Advanced Platform Features + +> **Goal**: Implement remaining spec modules that enhance the platform experience. +> +> **Duration**: 3–4 weeks (can be parallelized with other phases) + +### 12.1 Collaboration & CRDT (Priority: 🟡 Medium) + +> `spec/system` defines `CollaborationSession`, `CollaborativeCursor`, `CRDTState`, `OTOperation` for real-time co-editing. + +**Deliverables:** +- [ ] Create `hooks/useCollaboration.ts` + - Join/leave collaboration sessions + - Track cursor positions of other users + - Display presence indicators on form fields +- [ ] Create `components/realtime/CollaborationOverlay.tsx` — show other users' cursors +- [ ] Integrate with existing `useSubscription` for transport +- [ ] Tests for collaboration hook + +**Estimated Time**: 4–5 days + +### 12.2 Audit Log Viewer (Priority: 🟢 Low) + +> `spec/system` defines `AuditEvent`, `AuditConfig`, `AuditEventFilter` for compliance audit trails. + +**Deliverables:** +- [ ] Create `hooks/useAuditLog.ts` — fetch and filter audit events +- [ ] Create `components/audit/AuditTimeline.tsx` — timeline view of record changes +- [ ] Show on record detail views as a "History" tab +- [ ] Tests for audit log hook + +**Estimated Time**: 2–3 days + +### 12.3 Flow Visualization (Priority: 🟢 Low) + +> `spec/automation` defines `FlowSchema`, `FlowNode`, `FlowEdge` for visual workflow builders. Mobile should at minimum allow viewing flow definitions. + +**Deliverables:** +- [ ] Create `components/automation/FlowViewer.tsx` — read-only flow diagram + - Render nodes and edges as a visual graph + - Show node types (action, decision, loop) with icons +- [ ] Integrate with automation trigger status display +- [ ] Tests for flow viewer + +**Estimated Time**: 3–4 days + +### 12.4 State Machine Visualization (Priority: 🟢 Low) + +> `spec/automation` defines `StateMachineConfig`, `StateNodeConfig`, `Transition`. Currently `useWorkflowState` shows runtime state but not the full state machine configuration. + +**Deliverables:** +- [ ] Extend `useWorkflowState` or create `useStateMachine` hook + - Fetch full state machine config via `client.workflow.getConfig()` + - Display available states and transitions as a diagram +- [ ] Create `components/workflow/StateMachineViewer.tsx` +- [ ] Tests for state machine visualization + +**Estimated Time**: 2 days + +--- + ## Future Roadmap (Post v1.0) ### v1.1 — UX Refinements @@ -206,12 +506,29 @@ All development phases (0 through 5B) and most of Phase 6 are **complete**: | Task | Can Do Now? | Blocks v1.0? | Estimated Time | Priority | |------|-------------|-------------|----------------|----------| -| E2E Testing | ✅ Yes (needs backend) | ✅ Yes | 1–2 days | 🔴 High | -| Performance Profiling | ✅ Yes (needs devices) | ⚠️ Recommended | 2–3 days | 🟡 Medium | -| Integration Smoke Test | ✅ Yes (needs backend) | ⚠️ Recommended | 2–3 days | 🟡 Medium | -| App Store Assets | ✅ Yes | ✅ Yes | 3–5 days | 🔴 High | -| Legal & Compliance | ✅ Yes | ✅ Yes | 1–2 days | 🔴 High | -| Build & Submit | ✅ Yes | ✅ Yes | 1–2 weeks | 🔴 High | +| E2E Testing (7.1) | ✅ Yes (needs backend) | ✅ Yes | 1–2 days | 🔴 High | +| Performance Profiling (7.2) | ✅ Yes (needs devices) | ⚠️ Recommended | 2–3 days | 🟡 Medium | +| Integration Smoke Test (7.3) | ✅ Yes (needs backend) | ⚠️ Recommended | 2–3 days | 🟡 Medium | +| App Store Assets (8.1) | ✅ Yes | ✅ Yes | 3–5 days | 🔴 High | +| Legal & Compliance (8.2) | ✅ Yes | ✅ Yes | 1–2 days | 🔴 High | +| Build & Submit (8.3) | ✅ Yes | ✅ Yes | 1–2 weeks | 🔴 High | +| Automation Hook (9.1) | ✅ Yes | ⚠️ Recommended | 3–4 days | 🔴 High | +| Package Management (9.2) | ✅ Yes | ⚠️ Recommended | 2–3 days | 🔴 High | +| Analytics Explain (9.3) | ✅ Yes | No | 0.5 day | 🟡 Medium | +| Report View (10.1) | ✅ Yes | No | 3–4 days | 🟡 Medium | +| SDUI Page Renderer (10.2) | ✅ Yes | No | 4–5 days | 🟡 Medium | +| Theme Token Mapping (10.3) | ✅ Yes | No | 1–2 days | 🟢 Low | +| Widget System (10.4) | ✅ Yes | No | 2–3 days | 🟢 Low | +| AI Conversation Sessions (11.1) | ✅ Yes | No | 3–4 days | 🟡 Medium | +| RAG Integration (11.2) | ⚠️ Needs server RAG | No | 2–3 days | 🟡 Medium | +| MCP Awareness (11.3) | ⚠️ Needs server MCP | No | 2 days | 🟢 Low | +| Agent Orchestration (11.4) | ⚠️ Needs server agents | No | 3–4 days | 🟢 Low | +| Collaboration/CRDT (12.1) | ⚠️ Needs server CRDT | No | 4–5 days | 🟡 Medium | +| Audit Log (12.2) | ✅ Yes | No | 2–3 days | 🟢 Low | +| Flow Visualization (12.3) | ✅ Yes | No | 3–4 days | 🟢 Low | +| State Machine Viz (12.4) | ✅ Yes | No | 2 days | 🟢 Low | + +**Total estimated effort for Phase 9–12**: ~6–8 weeks (can overlap with Phases 7–8) --- @@ -226,6 +543,16 @@ All development phases (0 through 5B) and most of Phase 6 are **complete**: 7. ☐ TestFlight / internal testing completed (minimum 1 week) 8. ☐ App Store / Play Store review approved +## Success Criteria for v1.1 (Spec v2.0.4 Full Compliance) + +1. ☐ Phase 9 complete — Automation hook, package management, analytics explain +2. ☐ Phase 10 complete — Report views, SDUI pages, theme tokens +3. ☐ Phase 11 complete — AI sessions, RAG, MCP, agents +4. ☐ Phase 12 complete — Collaboration, audit, flow viz, state machine +5. ☐ All new hooks exported from `hooks/useObjectStack.ts` barrel +6. ☐ All new hooks have unit tests +7. ☐ SDK-GAP-ANALYSIS.md updated to reflect v2.0.4 compliance + --- ## For SDK Team — Feedback @@ -241,7 +568,24 @@ The following hooks were built on the mobile side using `useClient()`. Consider | `useAI()` | `client.ai.*` | NLQ, chat, suggest, insights | | `useServerTranslations()` | `client.i18n.*` | Server-side translation loading | | `useSavedViews()` | `client.views.*` | View CRUD with optimistic updates | +| `useAutomation()` | `client.automation.*` | 🆕 Trigger automation flows | +| `usePackageManagement()` | `client.packages.*` | 🆕 Package lifecycle (install/enable/disable) | +| `useRAG()` | `client.ai.rag?` | 🆕 Needs server-side RAG endpoint | +| `useCollaboration()` | `client.realtime.*` | 🆕 CRDT co-editing sessions | + +### Requested New Client-React Hooks + +The following hooks would benefit all ObjectStack frontend implementations if upstreamed to `@objectstack/client-react`: + +1. **`useAutomation()`** — Trigger and monitor automation flows +2. **`usePackages()`** — Package lifecycle management +3. **`useApprovals()`** — Pending approval list and actions +4. **`useConversation()`** — AI conversation session with persistence +5. **`useRAG()`** — RAG pipeline query with source citations +6. **`useCollaboration()`** — Real-time co-editing with cursor tracking +7. **`useAuditLog()`** — Audit event timeline for records +8. **`useReport()`** — Report query and rendering --- -*Last updated: 2026-02-09. See [ROADMAP.md](./ROADMAP.md) for full development history and [PROJECT-STATUS.md](./PROJECT-STATUS.md) for detailed status report.* +*Last updated: 2026-02-10. See [ROADMAP.md](./ROADMAP.md) for full development history and [PROJECT-STATUS.md](./PROJECT-STATUS.md) for detailed status report.* diff --git a/docs/PROJECT-STATUS.md b/docs/PROJECT-STATUS.md index 36b839d..25650f4 100644 --- a/docs/PROJECT-STATUS.md +++ b/docs/PROJECT-STATUS.md @@ -1,14 +1,17 @@ # ObjectStack Mobile — Project Status Report -> **Date**: 2026-02-09 +> **Date**: 2026-02-10 > **Version**: 1.0.0 -> **Status**: Development In Progress (SDK APIs Ready) +> **Status**: Development Complete — Entering Spec v2.0.4 Alignment Phase +> **SDK**: `@objectstack/client@2.0.4`, `@objectstack/client-react@2.0.4`, `@objectstack/spec@2.0.4` --- ## Executive Summary -The ObjectStack Mobile client has successfully completed **all development phases** (0 through 5B) plus most of Phase 6 (Production Readiness). With the v2.0.1 SDK upgrade, all 13 API namespaces are fully implemented with TypeScript type exports. All 493 unit and integration tests pass successfully across 58 test suites. +The ObjectStack Mobile client has successfully completed **all development phases** (0 through 5B) plus most of Phase 6 (Production Readiness). With the v2.0.4 SDK upgrade, all 13 API namespaces are fully implemented with TypeScript type exports. All 493 unit and integration tests pass successfully across 58 test suites. + +A comprehensive audit against `@objectstack/spec@2.0.4` (15 protocol modules) was conducted on 2026-02-10. This identified **15 protocol compliance gaps** across automation, AI, UI rendering, and collaboration — detailed in [NEXT-PHASE.md](./NEXT-PHASE.md) Phase 9–12 and [SDK-GAP-ANALYSIS.md](./SDK-GAP-ANALYSIS.md). ### Key Achievements @@ -30,6 +33,13 @@ The ObjectStack Mobile client has successfully completed **all development phase - Real-device performance profiling - App Store / Play Store submission preparation +🆕 **Spec v2.0.4 Alignment (Post-GA or Parallel)**: +- Automation trigger hook and approval process UI (Phase 9.1) +- Full package management UI (Phase 9.2) +- Report view renderer and SDUI page composition (Phase 10) +- AI conversation sessions, RAG, MCP, agent orchestration (Phase 11) +- Collaboration/CRDT, audit log, flow visualization (Phase 12) + ## Development Phase Status ### Phase 0: Foundation ✅ COMPLETE diff --git a/docs/SDK-GAP-ANALYSIS.md b/docs/SDK-GAP-ANALYSIS.md index 7a6087d..6660d77 100644 --- a/docs/SDK-GAP-ANALYSIS.md +++ b/docs/SDK-GAP-ANALYSIS.md @@ -1,8 +1,8 @@ # @objectstack/client SDK — Gap Analysis Report -> **Version analyzed**: `@objectstack/client@2.0.1`, `@objectstack/client-react@2.0.1`, `@objectstack/spec@2.0.1` +> **Version analyzed**: `@objectstack/client@2.0.4`, `@objectstack/client-react@2.0.4`, `@objectstack/spec@2.0.4` > -> **Date**: 2026-02-09 (Updated after v2.0.1 upgrade) +> **Date**: 2026-02-10 (Updated after spec v2.0.4 protocol audit) > > **Purpose**: 列出 Mobile 客户端完成全部开发所需但 SDK 目前尚未提供(或未完善)的 API 与功能,供上游项目排期开发。 @@ -11,30 +11,57 @@ ## Table of Contents 1. [Executive Summary](#executive-summary) -2. [Current SDK Coverage](#current-sdk-coverage) -3. [Gap 1 — Views API (client.views)](#gap-1--views-api-clientviews) -4. [Gap 2 — Permission System API](#gap-2--permission-system-api) -5. [Gap 3 — Workflow & State Machine API](#gap-3--workflow--state-machine-api) -6. [Gap 4 — Real-Time / WebSocket API](#gap-4--real-time--websocket-api) -7. [Gap 5 — Push Notification Registration API](#gap-5--push-notification-registration-api) -8. [Gap 6 — AI / NLQ API](#gap-6--ai--nlq-api) -9. [Gap 7 — Batch Operations Optimization](#gap-7--batch-operations-optimization) -10. [Gap 8 — File & Storage React Hooks](#gap-8--file--storage-react-hooks) -11. [Gap 9 — i18n / Localization API](#gap-9--i18n--localization-api) -12. [Gap 10 — Analytics React Hooks](#gap-10--analytics-react-hooks) -13. [Gap 11 — client-react Hook Gaps](#gap-11--client-react-hook-gaps) -14. [Priority Summary](#priority-summary) -15. [Appendix: SDK API Surface Inventory](#appendix-sdk-api-surface-inventory) +2. [v2.0.4 Spec Audit — New Findings](#v204-spec-audit--new-findings) +3. [Current SDK Coverage](#current-sdk-coverage) +4. [Gap 1 — Views API (client.views)](#gap-1--views-api-clientviews) +5. [Gap 2 — Permission System API](#gap-2--permission-system-api) +6. [Gap 3 — Workflow & State Machine API](#gap-3--workflow--state-machine-api) +7. [Gap 4 — Real-Time / WebSocket API](#gap-4--real-time--websocket-api) +8. [Gap 5 — Push Notification Registration API](#gap-5--push-notification-registration-api) +9. [Gap 6 — AI / NLQ API](#gap-6--ai--nlq-api) +10. [Gap 7 — Batch Operations Optimization](#gap-7--batch-operations-optimization) +11. [Gap 8 — File & Storage React Hooks](#gap-8--file--storage-react-hooks) +12. [Gap 9 — i18n / Localization API](#gap-9--i18n--localization-api) +13. [Gap 10 — Analytics React Hooks](#gap-10--analytics-react-hooks) +14. [Gap 11 — client-react Hook Gaps](#gap-11--client-react-hook-gaps) +15. [Priority Summary](#priority-summary) +16. [Appendix: SDK API Surface Inventory](#appendix-sdk-api-surface-inventory) --- ## Executive Summary -ObjectStack Mobile 客户端目前已完成 Phase 0–3(基础框架、SDK 集成、渲染引擎、数据层),以及大部分 Phase 4A, 5A, 6(独立功能)。**v2.0.1 升级后,所有 SDK Gap 已解决,Phase 4B 和 5B 可以立即启动开发。** +ObjectStack Mobile 客户端目前已完成 Phase 0–6.2(基础框架、SDK 集成、渲染引擎、数据层、高级功能、生产监控)。**v2.0.4 已升级,所有 v2.0.1 Gap 已解决,Phase 4B 和 5B 已完成开发。** + +### v2.0.4 协议审计摘要 (2026-02-10) + +在对 `@objectstack/spec@2.0.4` 的 **15 个模块**(root, driver, data, system, auth, kernel, hub, ai, automation, api, ui, contracts, integration, studio, permission)进行完整审计后,发现以下新的协议合规差距: + +**新发现的合规差距** (spec v2.0.4): + +| Category | Spec Module | Client API | Mobile Status | Priority | +|----------|-------------|-----------|---------------|----------| +| **Automation Trigger Hook** | `spec/automation` | `client.automation.trigger()` | ⚠️ 仅在 ActionExecutor 中使用,无专用 hook | 🔴 High | +| **Package Management UI** | `spec/api` → packages | `client.packages.*` (6个方法) | ⚠️ 仅 `useAppDiscovery` 使用 `list()` | 🔴 High | +| **Analytics SQL Explain** | `spec/api` → analytics | `client.analytics.explain()` | ❌ 未使用 | 🟡 Medium | +| **Report View** | `spec/ui` → `ReportSchema` | — | ❌ 无报表视图渲染器 | 🟡 Medium | +| **SDUI Page Composition** | `spec/ui` → `PageSchema` | — | ❌ 无服务端驱动页面 | 🟡 Medium | +| **Widget System** | `spec/ui` → `WidgetManifest` | — | ❌ 无 Widget 注册系统 | 🟢 Low | +| **Theme Tokens** | `spec/ui` → `ThemeSchema` | — | ⚠️ NativeWind 未映射 spec 令牌 | 🟢 Low | +| **AI Conversation Session** | `spec/ai` → `ConversationSession` | — | ⚠️ useAI 无会话持久化 | 🟡 Medium | +| **RAG Pipeline** | `spec/ai` → `RAGPipelineConfig` | — | ❌ 未实现 | 🟡 Medium | +| **MCP Integration** | `spec/ai` → `MCPServerConfig` | — | ❌ 未实现 | 🟢 Low | +| **Agent Orchestration** | `spec/ai` → `AgentSchema` | — | ❌ 未实现 | 🟢 Low | +| **Approval Process UI** | `spec/automation` → `ApprovalProcess` | `client.workflow.approve/reject` | ⚠️ 无审批列表 UI | 🔴 High | +| **Collaboration/CRDT** | `spec/system` → `CollaborationSession` | — | ❌ 未实现 | 🟡 Medium | +| **Audit Log** | `spec/system` → `AuditEvent` | — | ❌ 未实现 | 🟢 Low | +| **Flow Visualization** | `spec/automation` → `FlowSchema` | — | ❌ 未实现 | 🟢 Low | + +> **详细改进方案**: 见 [NEXT-PHASE.md](./NEXT-PHASE.md) Phase 9–12 ### v2.0.1 更新摘要 (2026-02-09) -✅ **所有 Gap 已解决**: SDK v2.0.1 完整实现了全部 13 个 API 命名空间,并导出了 TypeScript 类型定义。 +✅ **所有核心 Gap 已解决**: SDK v2.0.1 完整实现了全部 13 个 API 命名空间,并导出了 TypeScript 类型定义。 **新增已解决 API**: - `client.views.*` — 完整类型化的 Views API (create/get/list/update/delete) @@ -45,7 +72,7 @@ ObjectStack Mobile 客户端目前已完成 Phase 0–3(基础框架、SDK 集 - `client.ai.*` — AI/NLQ API (nlq/chat/suggest/insights) - `client.i18n.*` — 国际化 API (getLocales/getTranslations/getFieldLabels) -### 剩余改进项 +### 改进项总览 | Category | Status | Impact | |----------|--------|--------| @@ -56,15 +83,61 @@ ObjectStack Mobile 客户端目前已完成 Phase 0–3(基础框架、SDK 集 | **Push Notification API** | ✅ **已解决 (v2.0.1)** | Phase 4B.5 解除阻塞 | | **AI/NLQ API** | ✅ **已解决 (v2.0.1)** | Phase 5B.1 解除阻塞 | | **Batch 优化** | ✅ **已改进 (v2.0.0)** | 性能可继续优化 | -| **Storage React Hooks** | ⚠️ client-react 缺失 | 可自建 hooks | +| **Storage React Hooks** | ⚠️ client-react 缺失 | 已自建 `useFileUpload` hook | | **i18n API** | ✅ **已解决 (v2.0.1)** | Phase 5B.2 解除阻塞 | -| **Analytics React Hooks** | ⚠️ client-react 缺失 | 可用 hooks wrapper 优化 | +| **Analytics React Hooks** | ⚠️ client-react 缺失 | 已自建 `useAnalyticsQuery/Meta` hooks | +| **Automation Hook** | 🆕 **需要新 hook (v2.0.4)** | Phase 9.1 | +| **Package Management** | 🆕 **需要扩展 (v2.0.4)** | Phase 9.2 | +| **Report View** | 🆕 **需要新渲染器 (v2.0.4)** | Phase 10.1 | +| **SDUI Page Renderer** | 🆕 **需要新能力 (v2.0.4)** | Phase 10.2 | +| **AI Sessions/RAG/MCP** | 🆕 **需要新 hooks (v2.0.4)** | Phase 11 | +| **Collaboration** | 🆕 **需要新能力 (v2.0.4)** | Phase 12.1 | + +--- + +## v2.0.4 Spec Audit — New Findings + +### 审计方法 + +对 `@objectstack/spec@2.0.4` 的全部 15 个导出模块进行了完整协议扫描,比对 `@objectstack/client@2.0.4` 的 API surface 和 Mobile App 的现有实现。 + +### Spec 模块覆盖率 + +| Spec Module | Schemas | Client Exposed | Mobile Implemented | Coverage | +|-------------|---------|---------------|-------------------|----------| +| `spec/api` | ~200+ types | ✅ 完整 | ✅ 95%+ | 🟢 | +| `spec/data` | ~60 types (Field, Query, Filter, Driver) | ✅ 通过 client.data | ✅ 完整 | 🟢 | +| `spec/ui` | ~60 types (View, Form, Dashboard, Report, Page, Widget, Theme) | ⚠️ 部分 (通过 meta) | ⚠️ 80% (缺 Report, Page, Widget) | 🟡 | +| `spec/system` | ~200+ types (Cache, Storage, Logging, Audit, Collaboration, CRDT) | ⚠️ 部分 | ⚠️ 50% (缺 Collaboration, Audit) | 🟡 | +| `spec/ai` | ~100+ types (Agent, RAG, MCP, Conversation, Cost) | ⚠️ 仅 NLQ/Chat/Suggest/Insights | ⚠️ 30% (缺 RAG, MCP, Agent, Session) | 🔴 | +| `spec/automation` | ~50 types (Flow, ETL, Approval, StateMachine, Connector) | ⚠️ 仅 trigger() | ⚠️ 20% (仅 trigger in ActionExecutor) | 🔴 | +| `spec/kernel` | ~150+ types (Plugin, Event, FeatureFlag, Metadata) | ❌ 不适用 (服务端) | — | — | +| `spec/hub` | ~30 types (Tenant, Registry, Plans) | ⚠️ 部分 | ❌ 未实现 | 🔴 | +| `spec/contracts` | ~15 interfaces (IDataEngine, IHttpServer, IServiceRegistry) | ❌ 不适用 (服务端接口) | — | — | +| `spec/integration` | ~80 types (Connectors, FileStorage, MessageQueue, GitHub, Vercel) | ❌ 不适用 (服务端) | — | — | +| `spec/studio` | ~15 types (StudioPlugin, Contributions) | ❌ 不适用 (桌面端) | — | — | +| `spec/permission` | (通过 api 模块) | ✅ 通过 client.permissions | ✅ 完整 | 🟢 | + +### 关键协议合规要求 + +根据 `@objectstack/spec/prompts/implement-objectui.md`,Mobile 端必须遵循以下规则: + +1. **Rule #1: Server-Driven UI (SDUI)** — UI 必须根据 `PageSchema` 和 `ViewSchema` 动态渲染,不可硬编码页面布局 +2. **Rule #2: Metadata-Aware Components** — 组件必须接受 `ViewSchema` 作为 props +3. **Rule #3: Action Abstraction** — 按钮执行 `ActionSchema` 定义,非任意代码 +4. **Rule #4: Global Theming** — 样式基于 `ThemeSchema` 令牌 + +**当前合规状态:** +- Rule #1: ⚠️ 部分合规 (视图渲染器接受 metadata,但缺少 PageSchema 页面组合) +- Rule #2: ✅ 合规 (所有渲染器接受 metadata 配置) +- Rule #3: ✅ 合规 (`ActionExecutor` 执行 ActionSchema) +- Rule #4: ⚠️ 部分合规 (使用 NativeWind,但未映射 spec ThemeSchema 令牌) --- ## Current SDK Coverage -### `@objectstack/client@2.0.1` — 已有 API +### `@objectstack/client@2.0.4` — 已有 API 以下 API 在 SDK 中有完整类型定义且 Mobile 端已成功集成: @@ -151,7 +224,7 @@ QueryBuilder ✅ 链式查询构建器类 FilterBuilder ✅ 链式过滤器构建器类 ``` -### `@objectstack/client-react@2.0.1` — 已有 Hooks +### `@objectstack/client-react@2.0.4` — 已有 Hooks ``` ObjectStackProvider ✅ Context provider