feat: Meeting Assistant MVP - Complete implementation

Enterprise Meeting Knowledge Management System with: Backend (FastAPI): - Authentication proxy with JWT (pj-auth-api integration) - MySQL database with 4 tables (users, meetings, conclusions, actions) - Meeting CRUD with system code generation (C-YYYYMMDD-XX, A-YYYYMMDD-XX) - Dify LLM integration for AI summarization - Excel export with openpyxl - 20 unit tests (all passing) Client (Electron): - Login page with company auth - Meeting list with create/delete - Meeting detail with real-time transcription - Editable transcript textarea (single block, easy editing) - AI summarization with conclusions/action items - 5-second segment recording (efficient for long meetings) Sidecar (Python): - faster-whisper medium model with int8 quantization - ONNX Runtime VAD (lightweight, ~20MB vs PyTorch ~2GB) - Chinese punctuation processing - OpenCC for Traditional Chinese conversion - Anti-hallucination parameters - Auto-cleanup of temp audio files OpenSpec: - add-meeting-assistant-mvp (47 tasks, archived) - add-realtime-transcription (29 tasks, archived) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-10 20:17:44 +08:00
commit 8b6184ecc5
65 changed files with 10510 additions and 0 deletions
--- a/openspec/specs/ai-summarization/spec.md
+++ b/openspec/specs/ai-summarization/spec.md
@@ -0,0 +1,49 @@
+# ai-summarization Specification
+
+## Purpose
+TBD - created by archiving change add-meeting-assistant-mvp. Update Purpose after archive.
+## Requirements
+### Requirement: Dify Integration
+The middleware server SHALL integrate with Dify LLM at https://dify.theaken.com/v1 for transcript summarization.
+
+#### Scenario: Successful summarization
+- **WHEN** user submits POST /api/ai/summarize with transcript text
+- **THEN** the server SHALL call Dify API and return structured JSON with conclusions and action_items
+
+#### Scenario: Dify timeout handling
+- **WHEN** Dify API does not respond within timeout period
+- **THEN** the server SHALL return HTTP 504 with timeout error and client can retry
+
+#### Scenario: Dify error handling
+- **WHEN** Dify API returns error (500, rate limit, etc.)
+- **THEN** the server SHALL return appropriate HTTP error with details
+
+### Requirement: Structured Output Format
+The AI summarization SHALL return structured data with conclusions and action items.
+
+#### Scenario: Complete structured response
+- **WHEN** transcript contains clear decisions and assignments
+- **THEN** response SHALL include conclusions array and action_items array with content, owner, due_date fields
+
+#### Scenario: Partial data extraction
+- **WHEN** transcript lacks explicit owner or due_date for action items
+- **THEN** those fields SHALL be empty strings allowing manual completion
+
+### Requirement: Dify Prompt Configuration
+The Dify workflow SHALL be configured with appropriate system prompt for meeting summarization.
+
+#### Scenario: System prompt behavior
+- **WHEN** transcript is sent to Dify
+- **THEN** Dify SHALL use configured prompt to extract conclusions and action_items in JSON format
+
+### Requirement: Manual Data Completion
+The Electron client SHALL allow users to manually complete missing AI-extracted data.
+
+#### Scenario: Fill missing owner
+- **WHEN** AI returns action item without owner
+- **THEN** user SHALL be able to select or type owner name in the UI
+
+#### Scenario: Fill missing due date
+- **WHEN** AI returns action item without due_date
+- **THEN** user SHALL be able to select date using date picker
+
--- a/openspec/specs/authentication/spec.md
+++ b/openspec/specs/authentication/spec.md
@@ -0,0 +1,46 @@
+# authentication Specification
+
+## Purpose
+TBD - created by archiving change add-meeting-assistant-mvp. Update Purpose after archive.
+## Requirements
+### Requirement: Login Proxy
+The middleware server SHALL proxy login requests to the company Auth API at https://pj-auth-api.vercel.app/api/auth/login.
+
+#### Scenario: Successful login
+- **WHEN** user submits valid credentials to POST /api/login
+- **THEN** the server SHALL forward to Auth API and return the JWT token
+
+#### Scenario: Admin role detection
+- **WHEN** user logs in with email ymirliu@panjit.com.tw
+- **THEN** the response JWT payload SHALL include role: "admin"
+
+#### Scenario: Invalid credentials
+- **WHEN** user submits invalid credentials
+- **THEN** the server SHALL return HTTP 401 with error message from Auth API
+
+### Requirement: Token Validation
+The middleware server SHALL validate JWT tokens on protected endpoints.
+
+#### Scenario: Valid token access
+- **WHEN** request includes valid JWT in Authorization header
+- **THEN** the request SHALL proceed to the endpoint handler
+
+#### Scenario: Expired token
+- **WHEN** request includes expired JWT
+- **THEN** the server SHALL return HTTP 401 with "token_expired" error code
+
+#### Scenario: Missing token
+- **WHEN** request to protected endpoint lacks Authorization header
+- **THEN** the server SHALL return HTTP 401 with "token_required" error code
+
+### Requirement: Token Auto-Refresh
+The Electron client SHALL implement automatic token refresh before expiration.
+
+#### Scenario: Proactive refresh
+- **WHEN** token approaches expiration (within 5 minutes) during active session
+- **THEN** the client SHALL request new token transparently without user interruption
+
+#### Scenario: Refresh during long meeting
+- **WHEN** user is in a meeting session lasting longer than token validity
+- **THEN** the client SHALL maintain authentication through automatic refresh
+
--- a/openspec/specs/excel-export/spec.md
+++ b/openspec/specs/excel-export/spec.md
@@ -0,0 +1,49 @@
+# excel-export Specification
+
+## Purpose
+TBD - created by archiving change add-meeting-assistant-mvp. Update Purpose after archive.
+## Requirements
+### Requirement: Excel Report Generation
+The middleware server SHALL generate Excel reports from meeting data using templates.
+
+#### Scenario: Successful export
+- **WHEN** user requests GET /api/meetings/:id/export
+- **THEN** server SHALL generate Excel file and return as downloadable stream
+
+#### Scenario: Export non-existent meeting
+- **WHEN** user requests export for non-existent meeting ID
+- **THEN** server SHALL return HTTP 404
+
+### Requirement: Template-based Generation
+The Excel export SHALL use openpyxl with template files.
+
+#### Scenario: Placeholder replacement
+- **WHEN** Excel is generated
+- **THEN** placeholders ({{subject}}, {{time}}, {{chair}}, etc.) SHALL be replaced with actual meeting data
+
+#### Scenario: Dynamic row insertion
+- **WHEN** meeting has multiple conclusions or action items
+- **THEN** rows SHALL be dynamically inserted to accommodate all items
+
+### Requirement: Complete Data Inclusion
+The exported Excel SHALL include all meeting metadata and AI-generated content.
+
+#### Scenario: Full metadata export
+- **WHEN** Excel is generated
+- **THEN** it SHALL include subject, meeting_time, location, chairperson, recorder, and attendees
+
+#### Scenario: Conclusions export
+- **WHEN** Excel is generated
+- **THEN** all conclusions SHALL be listed with their system codes
+
+#### Scenario: Action items export
+- **WHEN** Excel is generated
+- **THEN** all action items SHALL be listed with content, owner, due_date, status, and system code
+
+### Requirement: Template Management
+Admin users SHALL be able to manage Excel templates.
+
+#### Scenario: Admin template access
+- **WHEN** admin user accesses template management
+- **THEN** they SHALL be able to upload, view, and update Excel templates
+
--- a/openspec/specs/frontend-transcript/spec.md
+++ b/openspec/specs/frontend-transcript/spec.md
@@ -0,0 +1,62 @@
+# frontend-transcript Specification
+
+## Purpose
+TBD - created by archiving change add-realtime-transcription. Update Purpose after archive.
+## Requirements
+### Requirement: Editable Transcript Segments
+The frontend SHALL display transcribed text as individually editable segments that can be modified without disrupting ongoing transcription.
+
+#### Scenario: Display new segment
+- **WHEN** a new transcription segment is received from sidecar
+- **THEN** a new editable text block SHALL appear in the transcript area
+- **AND** the block SHALL be visually distinct (e.g., border, background)
+- **AND** the block SHALL be immediately editable
+
+#### Scenario: Edit existing segment
+- **WHEN** user modifies text in a segment
+- **THEN** only that segment's local data SHALL be updated
+- **AND** new incoming segments SHALL continue to append below
+- **AND** the edited segment SHALL show an "edited" indicator
+
+#### Scenario: Save merged transcript
+- **WHEN** user clicks Save button
+- **THEN** all segments (edited and unedited) SHALL be concatenated in order
+- **AND** the merged text SHALL be saved as transcript_blob
+
+### Requirement: Real-time Streaming UI
+The frontend SHALL provide clear visual feedback during streaming transcription.
+
+#### Scenario: Recording active indicator
+- **WHEN** streaming recording is active
+- **THEN** a pulsing recording indicator SHALL be visible
+- **AND** the current/active segment SHALL have distinct styling (e.g., highlighted border)
+- **AND** the Start Recording button SHALL change to Stop Recording
+
+#### Scenario: Processing indicator
+- **WHEN** audio is being processed but no text has appeared yet
+- **THEN** a "Processing..." indicator SHALL appear in the active segment area
+- **AND** the indicator SHALL disappear when text arrives
+
+#### Scenario: Streaming status display
+- **WHEN** streaming session is active
+- **THEN** the UI SHALL display segment count (e.g., "Segment 5/5")
+- **AND** total recording duration
+
+### Requirement: Audio Streaming IPC
+The Electron main process SHALL provide IPC handlers for continuous audio streaming between renderer and sidecar.
+
+#### Scenario: Start streaming
+- **WHEN** renderer calls `startRecordingStream()`
+- **THEN** main process SHALL send start_stream command to sidecar
+- **AND** return session confirmation to renderer
+
+#### Scenario: Stream audio data
+- **WHEN** renderer sends audio chunk via `streamAudioChunk(arrayBuffer)`
+- **THEN** main process SHALL convert WebM to PCM if needed
+- **AND** forward to sidecar stdin as base64-encoded audio_chunk command
+
+#### Scenario: Receive transcription
+- **WHEN** sidecar emits a segment result on stdout
+- **THEN** main process SHALL parse the JSON
+- **AND** forward to renderer via `transcription-segment` IPC event
+
--- a/openspec/specs/meeting-management/spec.md
+++ b/openspec/specs/meeting-management/spec.md
@@ -0,0 +1,75 @@
+# meeting-management Specification
+
+## Purpose
+TBD - created by archiving change add-meeting-assistant-mvp. Update Purpose after archive.
+## Requirements
+### Requirement: Create Meeting
+The system SHALL allow users to create meetings with required metadata.
+
+#### Scenario: Create meeting with all fields
+- **WHEN** user submits POST /api/meetings with subject, meeting_time, chairperson, location, recorder, attendees
+- **THEN** a new meeting record SHALL be created with auto-generated UUID and the meeting data SHALL be returned
+
+#### Scenario: Create meeting with missing required fields
+- **WHEN** user submits POST /api/meetings without subject or meeting_time
+- **THEN** the server SHALL return HTTP 400 with validation error details
+
+#### Scenario: Recorder defaults to current user
+- **WHEN** user creates meeting without specifying recorder
+- **THEN** the recorder field SHALL default to the logged-in user's email
+
+### Requirement: List Meetings
+The system SHALL allow users to retrieve a list of meetings.
+
+#### Scenario: List all meetings for admin
+- **WHEN** admin user requests GET /api/meetings
+- **THEN** all meetings SHALL be returned
+
+#### Scenario: List meetings for regular user
+- **WHEN** regular user requests GET /api/meetings
+- **THEN** only meetings where user is creator, recorder, or attendee SHALL be returned
+
+### Requirement: Get Meeting Details
+The system SHALL allow users to retrieve full meeting details including conclusions and action items.
+
+#### Scenario: Get meeting with related data
+- **WHEN** user requests GET /api/meetings/:id
+- **THEN** meeting record with all conclusions and action_items SHALL be returned
+
+#### Scenario: Get non-existent meeting
+- **WHEN** user requests GET /api/meetings/:id for non-existent ID
+- **THEN** the server SHALL return HTTP 404
+
+### Requirement: Update Meeting
+The system SHALL allow users to update meeting data, conclusions, and action items.
+
+#### Scenario: Update meeting metadata
+- **WHEN** user submits PUT /api/meetings/:id with updated fields
+- **THEN** the meeting record SHALL be updated and new data returned
+
+#### Scenario: Update action item status
+- **WHEN** user updates action item status to "Done"
+- **THEN** the action_items record SHALL reflect the new status
+
+### Requirement: Delete Meeting
+The system SHALL allow authorized users to delete meetings.
+
+#### Scenario: Admin deletes any meeting
+- **WHEN** admin user requests DELETE /api/meetings/:id
+- **THEN** the meeting and all related conclusions and action_items SHALL be deleted
+
+#### Scenario: User deletes own meeting
+- **WHEN** user requests DELETE /api/meetings/:id for meeting they created
+- **THEN** the meeting and all related data SHALL be deleted
+
+### Requirement: System Code Generation
+The system SHALL auto-generate unique system codes for conclusions and action items.
+
+#### Scenario: Generate conclusion code
+- **WHEN** a conclusion is created for a meeting on 2025-12-10
+- **THEN** the system_code SHALL follow format C-20251210-XX where XX is sequence number
+
+#### Scenario: Generate action item code
+- **WHEN** an action item is created for a meeting on 2025-12-10
+- **THEN** the system_code SHALL follow format A-20251210-XX where XX is sequence number
+
--- a/openspec/specs/middleware/spec.md
+++ b/openspec/specs/middleware/spec.md
@@ -0,0 +1,45 @@
+# middleware Specification
+
+## Purpose
+TBD - created by archiving change add-meeting-assistant-mvp. Update Purpose after archive.
+## Requirements
+### Requirement: FastAPI Server Configuration
+The middleware server SHALL be implemented using Python FastAPI framework with environment-based configuration.
+
+#### Scenario: Server startup with valid configuration
+- **WHEN** the server starts with valid .env file containing DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_NAME, DIFY_API_URL, DIFY_API_KEY
+- **THEN** the server SHALL start successfully and accept connections
+
+#### Scenario: Server startup with missing configuration
+- **WHEN** the server starts with missing required environment variables
+- **THEN** the server SHALL fail to start with descriptive error message
+
+### Requirement: Database Connection Pool
+The middleware server SHALL maintain a connection pool to the MySQL database at mysql.theaken.com:33306.
+
+#### Scenario: Database connection success
+- **WHEN** the server connects to MySQL with valid credentials
+- **THEN** a connection pool SHALL be established and queries SHALL execute successfully
+
+#### Scenario: Database connection failure
+- **WHEN** the database is unreachable
+- **THEN** the server SHALL return HTTP 503 with error details for affected endpoints
+
+### Requirement: Table Initialization
+The middleware server SHALL ensure all required tables exist on startup with the `meeting_` prefix.
+
+#### Scenario: Tables created on first run
+- **WHEN** the server starts and tables do not exist
+- **THEN** the server SHALL create meeting_users, meeting_records, meeting_conclusions, and meeting_action_items tables
+
+#### Scenario: Tables already exist
+- **WHEN** the server starts and tables already exist
+- **THEN** the server SHALL skip table creation and continue normally
+
+### Requirement: CORS Configuration
+The middleware server SHALL allow cross-origin requests from the Electron client.
+
+#### Scenario: CORS preflight request
+- **WHEN** Electron client sends OPTIONS request
+- **THEN** the server SHALL respond with appropriate CORS headers allowing the request
+
--- a/openspec/specs/transcription/spec.md
+++ b/openspec/specs/transcription/spec.md
@@ -0,0 +1,90 @@
+# transcription Specification
+
+## Purpose
+TBD - created by archiving change add-meeting-assistant-mvp. Update Purpose after archive.
+## Requirements
+### Requirement: Edge Speech-to-Text
+The Electron client SHALL perform speech-to-text conversion locally using faster-whisper int8 model.
+
+#### Scenario: Successful transcription
+- **WHEN** user records audio during a meeting
+- **THEN** the audio SHALL be transcribed locally without network dependency
+
+#### Scenario: Transcription on target hardware
+- **WHEN** running on i5 processor with 8GB RAM
+- **THEN** transcription SHALL complete within acceptable latency for real-time display
+
+### Requirement: Traditional Chinese Output
+The transcription engine SHALL output Traditional Chinese (繁體中文) text.
+
+#### Scenario: Simplified to Traditional conversion
+- **WHEN** whisper outputs Simplified Chinese characters
+- **THEN** OpenCC SHALL convert output to Traditional Chinese
+
+#### Scenario: Native Traditional Chinese
+- **WHEN** whisper outputs Traditional Chinese directly
+- **THEN** the text SHALL pass through unchanged
+
+### Requirement: Real-time Display
+The Electron client SHALL display transcription results in real-time.
+
+#### Scenario: Streaming transcription
+- **WHEN** user is recording
+- **THEN** transcribed text SHALL appear in the left panel within seconds of speech
+
+### Requirement: Python Sidecar
+The transcription engine SHALL be packaged as a Python sidecar using PyInstaller.
+
+#### Scenario: Sidecar startup
+- **WHEN** Electron app launches
+- **THEN** the Python sidecar containing faster-whisper and OpenCC SHALL be available
+
+#### Scenario: Sidecar communication
+- **WHEN** Electron sends audio data to sidecar
+- **THEN** transcribed text SHALL be returned via IPC
+
+### Requirement: Streaming Transcription Mode
+The sidecar SHALL support a streaming mode where audio chunks are continuously received and transcribed in real-time with VAD-triggered segmentation.
+
+#### Scenario: Start streaming session
+- **WHEN** sidecar receives `{"action": "start_stream"}` command
+- **THEN** it SHALL initialize audio buffer and VAD processor
+- **AND** respond with `{"status": "streaming", "session_id": "<uuid>"}`
+
+#### Scenario: Process audio chunk
+- **WHEN** sidecar receives `{"action": "audio_chunk", "data": "<base64_pcm>"}` during active stream
+- **THEN** it SHALL append audio to buffer and run VAD detection
+- **AND** if speech boundary detected, transcribe accumulated audio
+- **AND** emit `{"segment_id": <int>, "text": "<transcription>", "is_final": true}`
+
+#### Scenario: Stop streaming session
+- **WHEN** sidecar receives `{"action": "stop_stream"}` command
+- **THEN** it SHALL transcribe any remaining buffered audio
+- **AND** respond with `{"status": "stream_stopped", "total_segments": <int>}`
+
+### Requirement: VAD-based Speech Segmentation
+The sidecar SHALL use Voice Activity Detection to identify natural speech boundaries for segmentation.
+
+#### Scenario: Detect speech end
+- **WHEN** VAD detects silence exceeding 500ms after speech
+- **THEN** the accumulated speech audio SHALL be sent for transcription
+- **AND** a new segment SHALL begin for subsequent speech
+
+#### Scenario: Handle continuous speech
+- **WHEN** speech continues for more than 15 seconds without pause
+- **THEN** the sidecar SHALL force a segment boundary
+- **AND** transcribe the 15-second chunk to prevent excessive latency
+
+### Requirement: Punctuation in Transcription Output
+The sidecar SHALL output transcribed text with appropriate Chinese punctuation marks.
+
+#### Scenario: Add sentence-ending punctuation
+- **WHEN** transcription completes for a segment
+- **THEN** the output SHALL include period (。) at natural sentence boundaries
+- **AND** question marks (？) for interrogative sentences
+- **AND** commas (，) for clause breaks within sentences
+
+#### Scenario: Detect question patterns
+- **WHEN** transcribed text ends with question particles (嗎、呢、什麼、怎麼、為什麼)
+- **THEN** the punctuation processor SHALL append question mark (？)
+