85bd30b6ee
- SUMMARY.md: 6 service methods + 6 route handlers documented - STATE.md: advanced to plan 3/4, recorded metrics and decisions - ROADMAP.md: updated phase 24 progress (2/4 summaries)
118 lines
5.3 KiB
Markdown
118 lines
5.3 KiB
Markdown
---
|
|
phase: 24-search-history-branching
|
|
plan: "01"
|
|
subsystem: api
|
|
tags: [postgres, drizzle-orm, tsvector, fts, express, bookmarks, branching, export]
|
|
|
|
requires:
|
|
- phase: 24-00
|
|
provides: "DB schema for chat_message_bookmarks, parentConversationId/branchFromMessageId in chatConversations, content_search tsvector column, searchMessagesSchema/branchConversationSchema validators, ChatMessageSearchResult/ChatBookmark types"
|
|
|
|
provides:
|
|
- "searchMessages: tsvector FTS with ts_rank ranking, company-scoped via conversation join"
|
|
- "toggleBookmark: transactional insert-or-delete bookmark"
|
|
- "getBookmarks: paginated bookmarks with message and conversation join"
|
|
- "branchConversation: copies messages up to branch point into new child conversation"
|
|
- "listBranches: queries child conversations by parentConversationId"
|
|
- "exportConversation: Markdown and JSON export with agent name resolution"
|
|
- "Six Express route handlers: search, bookmark toggle, bookmark list, branch create, branch list, export download"
|
|
|
|
affects:
|
|
- "24-02 (UI hooks and API client wiring)"
|
|
- "24-03 (UI components for search/bookmark/branch)"
|
|
|
|
tech-stack:
|
|
added: []
|
|
patterns:
|
|
- "chatService(db) factory extended with new methods — same pattern as existing listConversations, addMessage"
|
|
- "tsvector FTS via raw sql`` template — content_search column is Postgres-generated stored, not in Drizzle schema"
|
|
- "Export route sets Content-Disposition + Content-Type headers, uses res.send(content)"
|
|
- "Transaction for bookmark toggle ensures atomicity of read-then-write"
|
|
|
|
key-files:
|
|
created: []
|
|
modified:
|
|
- "server/src/services/chat.ts"
|
|
- "server/src/routes/chat.ts"
|
|
|
|
key-decisions:
|
|
- "Used this.getConversation() reference in exportConversation to reuse existing notFound guard — avoids duplicate query logic"
|
|
- "searchMessages returns early with empty items when query is blank after trim — avoids FTS error on empty tsquery"
|
|
|
|
patterns-established:
|
|
- "Pattern: LEFT JOIN agents ON chatMessages.agentId = agents.id for agent name resolution in export"
|
|
- "Pattern: branchConversation uses lte(createdAt) to include branch point message in copy"
|
|
|
|
requirements-completed:
|
|
- CHAT-07
|
|
- CHAT-13
|
|
- CHAT-14
|
|
- HIST-04
|
|
- HIST-09
|
|
- HIST-10
|
|
- HIST-11
|
|
- PERF-04
|
|
|
|
duration: 12min
|
|
completed: 2026-04-01
|
|
---
|
|
|
|
# Phase 24 Plan 01: Search, Bookmarks, Branching, and Export Service + Routes Summary
|
|
|
|
**Six service methods and six route handlers for full-text search (tsvector/ts_rank), bookmark toggle/list, conversation branching with message copy, and Markdown/JSON export with agent name resolution**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 12 min
|
|
- **Started:** 2026-04-01T22:30:00Z
|
|
- **Completed:** 2026-04-01T22:42:00Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 2
|
|
|
|
## Accomplishments
|
|
|
|
- searchMessages uses tsvector FTS with `plainto_tsquery` and `ts_rank` ordering, company-scoped via inner join to chatConversations
|
|
- toggleBookmark runs in a transaction: checks for existing bookmark then either deletes (returns bookmarked: false) or inserts (returns bookmarked: true)
|
|
- getBookmarks joins bookmarks with messages and conversations, returning full ChatBookmarkWithMessage shape
|
|
- branchConversation copies all messages up to and including the branch point into a new child conversation with parentConversationId and branchFromMessageId set
|
|
- listBranches queries chatConversations by parentConversationId with deletedAt IS NULL guard
|
|
- exportConversation LEFT JOINs agents for name resolution; user messages use "You" as speaker; Markdown and JSON formats with sanitized filename slug
|
|
- All six route handlers use assertBoard guard; search validates with ZodError 400 response; export sets Content-Disposition and Content-Type headers
|
|
|
|
## Task Commits
|
|
|
|
1. **Task 1: Service methods** - `5170fc3e` (feat)
|
|
2. **Task 2: Express routes** - `9f9c9e32` (feat)
|
|
|
|
## Files Created/Modified
|
|
|
|
- `server/src/services/chat.ts` - Added 6 service methods: searchMessages, toggleBookmark, getBookmarks, branchConversation, listBranches, exportConversation
|
|
- `server/src/routes/chat.ts` - Added 6 route handlers: message search, bookmark toggle, bookmark list, branch create, branch list, export download
|
|
|
|
## Decisions Made
|
|
|
|
- Used `this.getConversation()` inside `exportConversation` to reuse the existing notFound guard without duplicating query logic
|
|
- `searchMessages` returns early with `{ items: [] }` when `query.trim()` is empty to avoid PostgreSQL error on an empty tsquery
|
|
- `branchConversation` uses `lte(chatMessages.createdAt, branchMsg.createdAt)` so the branch point message itself is included in the copy
|
|
|
|
## Deviations from Plan
|
|
|
|
None - plan executed exactly as written.
|
|
|
|
## Issues Encountered
|
|
|
|
Pre-existing TypeScript errors in `server/src/services/plugin-host-services.ts` and plugin-related files caused the full `tsc` build to report failures, but these are unrelated to this plan's scope. Verified with targeted `tsc --noEmit | grep chat` — no errors in chat files.
|
|
|
|
## User Setup Required
|
|
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- All six service methods and route handlers are implemented and TypeScript-clean
|
|
- API client and React Query hooks (Plan 24-02) can wire against these endpoints
|
|
- UI components (Plan 24-03) can consume the hooks built in 24-02
|
|
|
|
---
|
|
*Phase: 24-search-history-branching*
|
|
*Completed: 2026-04-01*
|