de721ffc05
- SUMMARY.md created with service/route implementation details - STATE.md: advanced to plan 5/6, recorded 6min duration, added 3 decisions - ROADMAP.md: updated phase 21 progress (5/6 summaries) - REQUIREMENTS.md: marked CHAT-04, CHAT-05, CHAT-06, HIST-05 complete
129 lines
5.3 KiB
Markdown
129 lines
5.3 KiB
Markdown
---
|
|
phase: 21-chat-foundation
|
|
plan: 03
|
|
subsystem: api
|
|
tags: [express, drizzle-orm, postgres, rest-api, chat, cursor-pagination, soft-delete]
|
|
|
|
requires:
|
|
- phase: 21-chat-foundation/21-01
|
|
provides: chat_conversations and chat_messages Drizzle schema tables
|
|
|
|
provides:
|
|
- chatService factory with 7 CRUD methods (createConversation, listConversations, getConversation, updateConversation, softDeleteConversation, listMessages, addMessage)
|
|
- chatRoutes factory with 7 REST endpoints mounted on Express app
|
|
- Chat schema validators exported from @paperclipai/shared
|
|
|
|
affects:
|
|
- 21-04 (chat panel UI needs these REST endpoints)
|
|
- 21-05 (conversation list sidebar uses listConversations pagination)
|
|
- 22+ (agent integration adds messages via addMessage)
|
|
|
|
tech-stack:
|
|
added: []
|
|
patterns:
|
|
- "chatService(db) factory pattern matching documentService, activityService conventions"
|
|
- "cursor-based pagination using limit+1 trick with hasMore boolean"
|
|
- "soft-delete via deletedAt IS NULL filter in WHERE clause"
|
|
- "auto-title idempotency: WHERE title IS NULL guard on UPDATE"
|
|
|
|
key-files:
|
|
created:
|
|
- server/src/services/chat.ts
|
|
- server/src/routes/chat.ts
|
|
- server/src/__tests__/chat-service.test.ts (replaced stubs)
|
|
- server/src/__tests__/chat-routes.test.ts (replaced stubs)
|
|
modified:
|
|
- server/src/app.ts
|
|
- packages/shared/src/index.ts
|
|
|
|
key-decisions:
|
|
- "Pitfall 3 (updatedAt bump): addMessage always updates chatConversations.updatedAt after inserting — ensures conversation list sort order stays correct"
|
|
- "Pitfall 5 (auto-title idempotency): WHERE title IS NULL guard makes auto-title set safe to call multiple times"
|
|
- "Missing export fix: createConversationSchema/updateConversationSchema/createMessageSchema were in validators/chat.ts but not re-exported from shared/src/index.ts"
|
|
|
|
patterns-established:
|
|
- "Route factory pattern: function chatRoutes(db: Db): Router"
|
|
- "Service factory pattern: function chatService(db: Db) returning methods object"
|
|
- "Cursor pagination: fetch limit+1, slice to limit, set hasMore=true if extra row found"
|
|
|
|
requirements-completed: [CHAT-04, CHAT-05, CHAT-06, HIST-05]
|
|
|
|
duration: 6min
|
|
completed: 2026-04-01
|
|
---
|
|
|
|
# Phase 21 Plan 03: Chat Service and REST API Summary
|
|
|
|
**Express REST API for conversation+message CRUD with cursor pagination, soft-delete, auto-title, and updatedAt bumping**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** ~6 min
|
|
- **Started:** 2026-04-01T16:46:00Z
|
|
- **Completed:** 2026-04-01T16:52:30Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 6
|
|
|
|
## Accomplishments
|
|
|
|
- `chatService` factory with 7 methods covering full conversation lifecycle and message CRUD
|
|
- `chatRoutes` factory with 7 REST endpoints gated by `assertBoard`/`assertCompanyAccess`
|
|
- Routes mounted in `app.ts` as `api.use(chatRoutes(db))`
|
|
- 32 vitest tests passing (21 service, 11 route)
|
|
|
|
## Task Commits
|
|
|
|
1. **Task 1: Create chat service** - `4c344d46` (feat)
|
|
2. **Task 2: Create chat routes and mount in app.ts** - `563442e5` (feat)
|
|
|
|
## Files Created/Modified
|
|
|
|
- `server/src/services/chat.ts` - chatService factory with 7 CRUD methods
|
|
- `server/src/routes/chat.ts` - chatRoutes factory with 7 REST endpoints
|
|
- `server/src/__tests__/chat-service.test.ts` - 21 unit tests for chatService
|
|
- `server/src/__tests__/chat-routes.test.ts` - 11 integration tests for chatRoutes
|
|
- `server/src/app.ts` - Added chatRoutes import and `api.use(chatRoutes(db))`
|
|
- `packages/shared/src/index.ts` - Added chat schema exports
|
|
|
|
## Decisions Made
|
|
|
|
- Cursor pagination uses `limit+1` fetch pattern with `hasMore` boolean and `nextCursor` ISO string
|
|
- `listConversations` default limit 30/max 100; `listMessages` default limit 50/max 200
|
|
- Auto-title: `content.slice(0, 60)` with `WHERE title IS NULL` guard (idempotent)
|
|
- `updateConversation` accepts `pinnedAt`/`archivedAt` as ISO strings and converts to Date objects
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 2 - Missing Critical] Chat validator schemas not exported from @paperclipai/shared**
|
|
- **Found during:** Task 2 (chat-routes.test.ts returning 500 on POST routes)
|
|
- **Issue:** `createConversationSchema`, `updateConversationSchema`, and `createMessageSchema` existed in `packages/shared/src/validators/chat.ts` and were re-exported from `validators/index.ts` but were missing from the main `packages/shared/src/index.ts`. Any import of these from `@paperclipai/shared` would silently fail at runtime.
|
|
- **Fix:** Added explicit named exports for all three schemas and their types to `packages/shared/src/index.ts`
|
|
- **Files modified:** `packages/shared/src/index.ts`
|
|
- **Verification:** Tests pass; no TypeScript errors in shared package
|
|
- **Committed in:** `563442e5` (Task 2 commit)
|
|
|
|
---
|
|
|
|
**Total deviations:** 1 auto-fixed (1 missing critical export)
|
|
**Impact on plan:** Critical fix — without this, all POST/PATCH chat routes would throw runtime errors in production. No scope creep.
|
|
|
|
## Issues Encountered
|
|
|
|
None beyond the auto-fixed deviation above.
|
|
|
|
## User Setup Required
|
|
|
|
None — no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- Chat REST API fully operational; UI in Plan 04 can consume these endpoints
|
|
- Conversation and message CRUD all working with proper auth gates
|
|
- Pagination pattern established for Plan 05 (infinite scroll sidebar)
|
|
- No blockers
|
|
|
|
---
|
|
*Phase: 21-chat-foundation*
|
|
*Completed: 2026-04-01*
|