diff --git a/_bmad-output/implementation-artifacts/1-1-kh-i-t-o-h-t-ng-d-n-c-s-d-li-u-project-infrastructure-database-init.md b/_bmad-output/implementation-artifacts/1-1-kh-i-t-o-h-t-ng-d-n-c-s-d-li-u-project-infrastructure-database-init.md deleted file mode 100644 index 02357aaa5..000000000 --- a/_bmad-output/implementation-artifacts/1-1-kh-i-t-o-h-t-ng-d-n-c-s-d-li-u-project-infrastructure-database-init.md +++ /dev/null @@ -1,31 +0,0 @@ -# Story 1.1: Khởi tạo Hạ tầng Dự án & Cơ sở Dữ liệu (Project Infrastructure & Database Init) - -**Status:** done - -## PRD Requirements -As a Kỹ sư Hệ thống, -I want thiết lập bộ khung Next.js, FastAPI, và cấu hình Docker-compose cho Postgres/Redis/ZeroServer, -So that toàn bộ nền tảng có thể khởi chạy môi trường phát triển (Dev Environment) một cách nhất quán cho tất cả các team. -**Acceptance Criteria:** -**Given** môi trường dự án mới -**When** chạy lệnh `docker-compose -f docker/docker-compose.dev.yml up -d` -**Then** các containers Postgres 16 (với pgvector), Redis, Zero-Server, FastAPI, và Next.js khởi tạo thành công -**And** database tự động migrate được schema ban đầu bao gồm bảng `users` với quy tắc `snake_case`. - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/1-1-project-infrastructure-database-init.md b/_bmad-output/implementation-artifacts/1-1-project-infrastructure-database-init.md new file mode 100644 index 000000000..17da6dbf8 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-1-project-infrastructure-database-init.md @@ -0,0 +1,55 @@ +# Story 1.1: Khởi tạo Hạ tầng Dự án & Cơ sở Dữ liệu (Project Infrastructure & Database Init) + +**Status:** done +**Epic:** Epic 1 +**Story Key:** `1-1-project-infrastructure-database-init` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Kỹ sư Hệ thống, +I want thiết lập bộ khung Next.js, FastAPI, và cấu hình Docker-compose cho Postgres/Redis/ZeroServer, +So that toàn bộ nền tảng có thể khởi chạy môi trường phát triển (Dev Environment) một cách nhất quán cho tất cả các team. +**Acceptance Criteria:** +**Given** môi trường dự án mới +**When** chạy lệnh `docker-compose -f docker/docker-compose.dev.yml up -d` +**Then** các containers Postgres 16 (với pgvector), Redis, Zero-Server, FastAPI, và Next.js khởi tạo thành công +**And** database tự động migrate được schema ban đầu bao gồm bảng `users` với quy tắc `snake_case`. + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/1-2-backend-auth-api-jwt.md b/_bmad-output/implementation-artifacts/1-2-backend-auth-api-jwt.md new file mode 100644 index 000000000..8414e5f83 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-2-backend-auth-api-jwt.md @@ -0,0 +1,55 @@ +# Story 1.2: Triển khai Backend API Xác thực & JWT (Backend Auth API & JWT) + +**Status:** done +**Epic:** Epic 1 +**Story Key:** `1-2-backend-auth-api-jwt` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Người dùng, +I want gọi API an toàn để tạo tài khoản, đăng nhập và lấy mã Token (JWT), +So that hệ thống xác thực được danh tính của tôi và kích hoạt RLS (Row-level Security) bảo vệ dữ liệu trên Database Postgres. +**Acceptance Criteria:** +**Given** thông tin đăng nhập hợp lệ +**When** gửi request tới endpoint liên quan `/api/v1/auth/login` +**Then** hệ thống trả về mã JWT chứa userID hợp lệ, bọc trong cấu trúc Wrapper chuẩn `{ "data": {"token": "xxx"}, "error": null, "meta": null }` +**And** Cấu hình Row-Level Security (RLS) cơ bản cho bảng dữ liệu (người này không query được dữ liệu của người kia). + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/1-2-tri-n-khai-backend-api-x-c-th-c-jwt-backend-auth-api-jwt.md b/_bmad-output/implementation-artifacts/1-2-tri-n-khai-backend-api-x-c-th-c-jwt-backend-auth-api-jwt.md deleted file mode 100644 index b85afcd6d..000000000 --- a/_bmad-output/implementation-artifacts/1-2-tri-n-khai-backend-api-x-c-th-c-jwt-backend-auth-api-jwt.md +++ /dev/null @@ -1,31 +0,0 @@ -# Story 1.2: Triển khai Backend API Xác thực & JWT (Backend Auth API & JWT) - -**Status:** done - -## PRD Requirements -As a Người dùng, -I want gọi API an toàn để tạo tài khoản, đăng nhập và lấy mã Token (JWT), -So that hệ thống xác thực được danh tính của tôi và kích hoạt RLS (Row-level Security) bảo vệ dữ liệu trên Database Postgres. -**Acceptance Criteria:** -**Given** thông tin đăng nhập hợp lệ -**When** gửi request tới endpoint liên quan `/api/v1/auth/login` -**Then** hệ thống trả về mã JWT chứa userID hợp lệ, bọc trong cấu trúc Wrapper chuẩn `{ "data": {"token": "xxx"}, "error": null, "meta": null }` -**And** Cấu hình Row-Level Security (RLS) cơ bản cho bảng dữ liệu (người này không query được dữ liệu của người kia). - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/1-3-frontend-auth-ui.md b/_bmad-output/implementation-artifacts/1-3-frontend-auth-ui.md new file mode 100644 index 000000000..c1841a5fa --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-3-frontend-auth-ui.md @@ -0,0 +1,58 @@ +# Story 1.3: Giao diện Đăng nhập & Tích hợp Token vào Zero-Client (Frontend Auth UI) + +**Status:** done +**Epic:** Epic 1 +**Story Key:** `1-3-frontend-auth-ui` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Người dùng, +I want sử dụng giao diện trơn tru để đăng ký/đăng nhập, +So that tôi nhận được Token và ngay lập tức kết nối tới hệ thống dữ liệu Local-first an toàn qua Zero Client. +**Acceptance Criteria:** +**Given** tôi đang ở trạng thái khách (Guest) trên UI +**When** tôi điền form đăng nhập thành công +**Then** giao diện lưu token vào cục bộ và tự động khởi tạo instance `ZeroClient` để bắt đầu mở cầu nối WebSockets. +**And** khi tôi nhấn nút "Đăng xuất" (Log Out), hàm `onLogout()` tự động thực thi dọn dẹp sạch (purge) toàn bộ IndexedDB, chặn bảo mật. +**And** Giao diện (Form đăng nhập, nút bấm) ứng dụng quy chuẩn UX-DR1 (Màu Base Zinc/Accent Indigo, font Inter). +Người dùng dễ dàng kéo thả các tệp PDF/TXT lên hệ thống; hệ thống tự động bóc tách dữ liệu mượt mà trong nền mà không làm gián đoạn công việc. Họ nắm rõ tiến độ nạp file và làm chủ khối lượng tài liệu của mình. +**FRs covered:** FR1, FR2, FR3, FR4, FR12, FR13 + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/1-3-giao-di-n-ng-nh-p-t-ch-h-p-token-v-o-zero-client-frontend-auth-ui.md b/_bmad-output/implementation-artifacts/1-3-giao-di-n-ng-nh-p-t-ch-h-p-token-v-o-zero-client-frontend-auth-ui.md deleted file mode 100644 index 198fe054d..000000000 --- a/_bmad-output/implementation-artifacts/1-3-giao-di-n-ng-nh-p-t-ch-h-p-token-v-o-zero-client-frontend-auth-ui.md +++ /dev/null @@ -1,34 +0,0 @@ -# Story 1.3: Giao diện Đăng nhập & Tích hợp Token vào Zero-Client (Frontend Auth UI) - -**Status:** done - -## PRD Requirements -As a Người dùng, -I want sử dụng giao diện trơn tru để đăng ký/đăng nhập, -So that tôi nhận được Token và ngay lập tức kết nối tới hệ thống dữ liệu Local-first an toàn qua Zero Client. -**Acceptance Criteria:** -**Given** tôi đang ở trạng thái khách (Guest) trên UI -**When** tôi điền form đăng nhập thành công -**Then** giao diện lưu token vào cục bộ và tự động khởi tạo instance `ZeroClient` để bắt đầu mở cầu nối WebSockets. -**And** khi tôi nhấn nút "Đăng xuất" (Log Out), hàm `onLogout()` tự động thực thi dọn dẹp sạch (purge) toàn bộ IndexedDB, chặn bảo mật. -**And** Giao diện (Form đăng nhập, nút bấm) ứng dụng quy chuẩn UX-DR1 (Màu Base Zinc/Accent Indigo, font Inter). -Người dùng dễ dàng kéo thả các tệp PDF/TXT lên hệ thống; hệ thống tự động bóc tách dữ liệu mượt mà trong nền mà không làm gián đoạn công việc. Họ nắm rõ tiến độ nạp file và làm chủ khối lượng tài liệu của mình. -**FRs covered:** FR1, FR2, FR3, FR4, FR12, FR13 - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/2-1-celery-worker-pdf-parser.md b/_bmad-output/implementation-artifacts/2-1-celery-worker-pdf-parser.md new file mode 100644 index 000000000..ac086e302 --- /dev/null +++ b/_bmad-output/implementation-artifacts/2-1-celery-worker-pdf-parser.md @@ -0,0 +1,55 @@ +# Story 2.1: Khởi tạo Kiến trúc Tác vụ nền & Xử lý PDF (Celery Worker & PDF Parser) + +**Status:** done +**Epic:** Epic 2 +**Story Key:** `2-1-celery-worker-pdf-parser` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Kỹ sư Hệ thống, +I want xây dựng hệ thống worker bất đồng bộ (Celery + Redis) để bóc tách văn bản và tạo Vector Embeddings, +So that hệ thống API chính không bị nghẽn khi người dùng upload file, và có thể scale linh hoạt số lượng worker. +**Acceptance Criteria:** +**Given** phần mềm nhận một file PDF/TXT được đẩy vào hàng đợi (Queue) +**When** worker được phân công thực thi tác vụ +**Then** tiến trình phân giải text và nạp Vector qua pgvector hoàn thành dưới 30s (đối với file <5MB) +**And** trạng thái bản ghi tài liệu trên Database được cập nhật tuần tự (Processing -> Completed hoặc Error). + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/2-1-kh-i-t-o-ki-n-tr-c-t-c-v-n-n-x-l-pdf-celery-worker-pdf-parser.md b/_bmad-output/implementation-artifacts/2-1-kh-i-t-o-ki-n-tr-c-t-c-v-n-n-x-l-pdf-celery-worker-pdf-parser.md deleted file mode 100644 index 70886e4ca..000000000 --- a/_bmad-output/implementation-artifacts/2-1-kh-i-t-o-ki-n-tr-c-t-c-v-n-n-x-l-pdf-celery-worker-pdf-parser.md +++ /dev/null @@ -1,31 +0,0 @@ -# Story 2.1: Khởi tạo Kiến trúc Tác vụ nền & Xử lý PDF (Celery Worker & PDF Parser) - -**Status:** done - -## PRD Requirements -As a Kỹ sư Hệ thống, -I want xây dựng hệ thống worker bất đồng bộ (Celery + Redis) để bóc tách văn bản và tạo Vector Embeddings, -So that hệ thống API chính không bị nghẽn khi người dùng upload file, và có thể scale linh hoạt số lượng worker. -**Acceptance Criteria:** -**Given** phần mềm nhận một file PDF/TXT được đẩy vào hàng đợi (Queue) -**When** worker được phân công thực thi tác vụ -**Then** tiến trình phân giải text và nạp Vector qua pgvector hoàn thành dưới 30s (đối với file <5MB) -**And** trạng thái bản ghi tài liệu trên Database được cập nhật tuần tự (Processing -> Completed hoặc Error). - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/2-2-tri-n-khai-api-t-i-l-n-gi-i-h-n-rate-limit-upload-api-rate-limiting.md b/_bmad-output/implementation-artifacts/2-2-tri-n-khai-api-t-i-l-n-gi-i-h-n-rate-limit-upload-api-rate-limiting.md deleted file mode 100644 index 7aa3654a0..000000000 --- a/_bmad-output/implementation-artifacts/2-2-tri-n-khai-api-t-i-l-n-gi-i-h-n-rate-limit-upload-api-rate-limiting.md +++ /dev/null @@ -1,31 +0,0 @@ -# Story 2.2: Triển khai API Tải lên & Giới hạn Rate Limit (Upload API & Rate Limiting) - -**Status:** done - -## PRD Requirements -As a Kỹ sư Backend, -I want xây dựng endpoint FastAPI cho việc upload tài liệu kèm cơ chế Rate Limit, -So that server tiếp nhận an toàn và ngăn chặn upload spam quá mức hệ thống cho phép. -**Acceptance Criteria:** -**Given** người dùng đăng nhập hợp lệ -**When** đính kèm file và gửi POST tới `/api/v1/documents` -**Then** hệ thống check user token, lưu file vô Storage, tạo record ở DB với status 'Queue', và trigger đẩy task vào Celery -**And** nếu user push liên tục quá mức quy định (token/hạn mức tải), API sẽ trả về lỗi `429 Too Many Requests` bọc trong error format chuẩn. - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/2-2-upload-api-rate-limiting.md b/_bmad-output/implementation-artifacts/2-2-upload-api-rate-limiting.md new file mode 100644 index 000000000..29aa2410e --- /dev/null +++ b/_bmad-output/implementation-artifacts/2-2-upload-api-rate-limiting.md @@ -0,0 +1,55 @@ +# Story 2.2: Triển khai API Tải lên & Giới hạn Rate Limit (Upload API & Rate Limiting) + +**Status:** done +**Epic:** Epic 2 +**Story Key:** `2-2-upload-api-rate-limiting` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Kỹ sư Backend, +I want xây dựng endpoint FastAPI cho việc upload tài liệu kèm cơ chế Rate Limit, +So that server tiếp nhận an toàn và ngăn chặn upload spam quá mức hệ thống cho phép. +**Acceptance Criteria:** +**Given** người dùng đăng nhập hợp lệ +**When** đính kèm file và gửi POST tới `/api/v1/documents` +**Then** hệ thống check user token, lưu file vô Storage, tạo record ở DB với status 'Queue', và trigger đẩy task vào Celery +**And** nếu user push liên tục quá mức quy định (token/hạn mức tải), API sẽ trả về lỗi `429 Too Many Requests` bọc trong error format chuẩn. + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/2-3-giao-di-n-qu-n-l-t-i-li-u-ch-b-o-syncing-kh-p-n-i-knowledge-base-ui-micro-sync-indicators.md b/_bmad-output/implementation-artifacts/2-3-giao-di-n-qu-n-l-t-i-li-u-ch-b-o-syncing-kh-p-n-i-knowledge-base-ui-micro-sync-indicators.md deleted file mode 100644 index 91d2e8d3c..000000000 --- a/_bmad-output/implementation-artifacts/2-3-giao-di-n-qu-n-l-t-i-li-u-ch-b-o-syncing-kh-p-n-i-knowledge-base-ui-micro-sync-indicators.md +++ /dev/null @@ -1,31 +0,0 @@ -# Story 2.3: Giao diện Quản lý Tài liệu & Chỉ báo Syncing Khớp nối (Knowledge Base UI & Micro-Sync Indicators) - -**Status:** done - -## PRD Requirements -As a Người dùng, -I want thấy ngay lập tức danh sách tài liệu đang có và dễ dàng tải file mới lên, -So that tôi biết file nào đã sẵn sàng để chat, file nào đang chạy nền mà không bị gián đoạn thao tác chuột. -**Acceptance Criteria:** -**Given** người dùng ở giao diện không gian làm việc (Workspace) -**When** có một tài liệu đang được tải lên hoặc xử lý (Processing) -**Then** UX hiển thị thanh tiến trình nhỏ ở góc trên màn hình / cạnh danh sách (Micro-Sync Indicator) và không được chặn màn hình (UX-DR5) -**And** danh sách tài liệu được lấy thông qua Zero-client tự động update state realtime khi worker xử lý xong (FR2, FR3). - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/2-3-knowledge-base-ui-micro-sync-indicators.md b/_bmad-output/implementation-artifacts/2-3-knowledge-base-ui-micro-sync-indicators.md new file mode 100644 index 000000000..6b88f2688 --- /dev/null +++ b/_bmad-output/implementation-artifacts/2-3-knowledge-base-ui-micro-sync-indicators.md @@ -0,0 +1,55 @@ +# Story 2.3: Giao diện Quản lý Tài liệu & Chỉ báo Syncing Khớp nối (Knowledge Base UI & Micro-Sync Indicators) + +**Status:** done +**Epic:** Epic 2 +**Story Key:** `2-3-knowledge-base-ui-micro-sync-indicators` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Người dùng, +I want thấy ngay lập tức danh sách tài liệu đang có và dễ dàng tải file mới lên, +So that tôi biết file nào đã sẵn sàng để chat, file nào đang chạy nền mà không bị gián đoạn thao tác chuột. +**Acceptance Criteria:** +**Given** người dùng ở giao diện không gian làm việc (Workspace) +**When** có một tài liệu đang được tải lên hoặc xử lý (Processing) +**Then** UX hiển thị thanh tiến trình nhỏ ở góc trên màn hình / cạnh danh sách (Micro-Sync Indicator) và không được chặn màn hình (UX-DR5) +**And** danh sách tài liệu được lấy thông qua Zero-client tự động update state realtime khi worker xử lý xong (FR2, FR3). + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/2-4-api-v-giao-di-n-x-a-t-i-li-u-kh-i-workspace-delete-document-flow.md b/_bmad-output/implementation-artifacts/2-4-api-v-giao-di-n-x-a-t-i-li-u-kh-i-workspace-delete-document-flow.md deleted file mode 100644 index 16f0513e4..000000000 --- a/_bmad-output/implementation-artifacts/2-4-api-v-giao-di-n-x-a-t-i-li-u-kh-i-workspace-delete-document-flow.md +++ /dev/null @@ -1,33 +0,0 @@ -# Story 2.4: API và Giao diện Xóa tài liệu khỏi Workspace (Delete Document Flow) - -**Status:** done - -## PRD Requirements -As a Người dùng, -I want chọn một tài liệu cũ và xóa hoàn toàn, -So that không gian lưu trữ được dọn dẹp và AI sẽ không bao giờ truy cập nội dung đó nữa. -**Acceptance Criteria:** -**Given** người dùng đang có tài liệu hiển thị trên danh sách -**When** người dùng click icon "Xoá" file -**Then** dữ liệu tài liệu lập tức bị loại bỏ khỏi giao diện UI do cơ chế optimism update của Zero -**And** trên Database, bản ghi bị xoá hoặc mark deleted, kèm theo việc dọn dẹp các Vectors rác liên quan trong background. -Người dùng có trải nghiệm truy vấn kho tài liệu "không độ trễ" (Instant Action) thông qua chat. Kết quả được stream về theo thời gian thực như một trợ lý xịn, tích hợp hệ thống Split-pane tinh tế để đối chiếu thẳng với Nguồn trích dẫn. -**FRs covered:** FR5, FR6, FR7 - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/2-4-delete-document-flow.md b/_bmad-output/implementation-artifacts/2-4-delete-document-flow.md new file mode 100644 index 000000000..bb51c5c30 --- /dev/null +++ b/_bmad-output/implementation-artifacts/2-4-delete-document-flow.md @@ -0,0 +1,57 @@ +# Story 2.4: API và Giao diện Xóa tài liệu khỏi Workspace (Delete Document Flow) + +**Status:** done +**Epic:** Epic 2 +**Story Key:** `2-4-delete-document-flow` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Người dùng, +I want chọn một tài liệu cũ và xóa hoàn toàn, +So that không gian lưu trữ được dọn dẹp và AI sẽ không bao giờ truy cập nội dung đó nữa. +**Acceptance Criteria:** +**Given** người dùng đang có tài liệu hiển thị trên danh sách +**When** người dùng click icon "Xoá" file +**Then** dữ liệu tài liệu lập tức bị loại bỏ khỏi giao diện UI do cơ chế optimism update của Zero +**And** trên Database, bản ghi bị xoá hoặc mark deleted, kèm theo việc dọn dẹp các Vectors rác liên quan trong background. +Người dùng có trải nghiệm truy vấn kho tài liệu "không độ trễ" (Instant Action) thông qua chat. Kết quả được stream về theo thời gian thực như một trợ lý xịn, tích hợp hệ thống Split-pane tinh tế để đối chiếu thẳng với Nguồn trích dẫn. +**FRs covered:** FR5, FR6, FR7 + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/3-1-api-t-o-qu-n-l-phi-n-chat-chat-session-api.md b/_bmad-output/implementation-artifacts/3-1-api-t-o-qu-n-l-phi-n-chat-chat-session-api.md deleted file mode 100644 index f8bac6aad..000000000 --- a/_bmad-output/implementation-artifacts/3-1-api-t-o-qu-n-l-phi-n-chat-chat-session-api.md +++ /dev/null @@ -1,31 +0,0 @@ -# Story 3.1: API Tạo & Quản lý Phiên Chat (Chat Session API) - -**Status:** done - -## PRD Requirements -As a Người dùng, -I want tạo một phiên trò chuyện (chat session) mới với AI, -So that tôi có thể bắt đầu một định mức hội thoại mới, tách bạch hoàn toàn với các chủ đề cũ. -**Acceptance Criteria:** -**Given** cửa sổ Chat -**When** tôi chọn lệnh "New Chat" hoặc nhập thẳng vào input đầu tiên -**Then** hệ thống tạo một "Session" ID mới trên Database và lưu tin nhắn đầu tiên của user (FR5, FR6) -**And** trả về data qua REST API theo wrapper chuẩn để client chốt phiên làm việc. - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/3-1-chat-session-api.md b/_bmad-output/implementation-artifacts/3-1-chat-session-api.md new file mode 100644 index 000000000..e059cb983 --- /dev/null +++ b/_bmad-output/implementation-artifacts/3-1-chat-session-api.md @@ -0,0 +1,55 @@ +# Story 3.1: API Tạo & Quản lý Phiên Chat (Chat Session API) + +**Status:** done +**Epic:** Epic 3 +**Story Key:** `3-1-chat-session-api` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Người dùng, +I want tạo một phiên trò chuyện (chat session) mới với AI, +So that tôi có thể bắt đầu một định mức hội thoại mới, tách bạch hoàn toàn với các chủ đề cũ. +**Acceptance Criteria:** +**Given** cửa sổ Chat +**When** tôi chọn lệnh "New Chat" hoặc nhập thẳng vào input đầu tiên +**Then** hệ thống tạo một "Session" ID mới trên Database và lưu tin nhắn đầu tiên của user (FR5, FR6) +**And** trả về data qua REST API theo wrapper chuẩn để client chốt phiên làm việc. + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/3-2-kh-i-rag-engine-c-ng-tr-streaming-sse-rag-engine-sse-endpoint.md b/_bmad-output/implementation-artifacts/3-2-kh-i-rag-engine-c-ng-tr-streaming-sse-rag-engine-sse-endpoint.md deleted file mode 100644 index 27f339a2e..000000000 --- a/_bmad-output/implementation-artifacts/3-2-kh-i-rag-engine-c-ng-tr-streaming-sse-rag-engine-sse-endpoint.md +++ /dev/null @@ -1,32 +0,0 @@ -# Story 3.2: Khối RAG Engine & Cổng trả Streaming SSE (RAG Engine & SSE Endpoint) - -**Status:** done - -## PRD Requirements -As a Kỹ sư Backend, -I want xây dựng khối RAG query bằng pgvector và đẩy dữ liệu về dạng Server-Sent Events (SSE), -So that AI có thể phản hồi từng chữ một (streaming) ngay khi lấy được ngữ cảnh, và đảm bảo chuẩn NFR-P1 (< 1.5s). -**Acceptance Criteria:** -**Given** backend nhận một câu hỏi của user và Session ID -**When** gọi tới Model AI (ví dụ OpenAI/Gemini) với ngữ cảnh lấy từ VectorDB -**Then** API `/api/v1/chat/stream` trả dòng response trả về dưới định dạng sự kiện SSE (text/event-stream) (FR7) -**And** ký tự đầu tiên (First token) về tới client dưới 1.5s -**And** ở cuối luồng stream trả về đính kèm bộ Metadata (Array các id/đoạn trích dẫn được dùng). - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/3-2-rag-engine-sse-endpoint.md b/_bmad-output/implementation-artifacts/3-2-rag-engine-sse-endpoint.md new file mode 100644 index 000000000..2f1f134a5 --- /dev/null +++ b/_bmad-output/implementation-artifacts/3-2-rag-engine-sse-endpoint.md @@ -0,0 +1,56 @@ +# Story 3.2: Khối RAG Engine & Cổng trả Streaming SSE (RAG Engine & SSE Endpoint) + +**Status:** done +**Epic:** Epic 3 +**Story Key:** `3-2-rag-engine-sse-endpoint` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Kỹ sư Backend, +I want xây dựng khối RAG query bằng pgvector và đẩy dữ liệu về dạng Server-Sent Events (SSE), +So that AI có thể phản hồi từng chữ một (streaming) ngay khi lấy được ngữ cảnh, và đảm bảo chuẩn NFR-P1 (< 1.5s). +**Acceptance Criteria:** +**Given** backend nhận một câu hỏi của user và Session ID +**When** gọi tới Model AI (ví dụ OpenAI/Gemini) với ngữ cảnh lấy từ VectorDB +**Then** API `/api/v1/chat/stream` trả dòng response trả về dưới định dạng sự kiện SSE (text/event-stream) (FR7) +**And** ký tự đầu tiên (First token) về tới client dưới 1.5s +**And** ở cuối luồng stream trả về đính kèm bộ Metadata (Array các id/đoạn trích dẫn được dùng). + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/3-3-chat-ui-sse-client.md b/_bmad-output/implementation-artifacts/3-3-chat-ui-sse-client.md new file mode 100644 index 000000000..c4ff0ccfc --- /dev/null +++ b/_bmad-output/implementation-artifacts/3-3-chat-ui-sse-client.md @@ -0,0 +1,55 @@ +# Story 3.3: Giao diện Khung Chat & Tiếp nhận Streaming (Chat UI & SSE Client) + +**Status:** done +**Epic:** Epic 3 +**Story Key:** `3-3-chat-ui-sse-client` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Người dùng, +I want thấy AI gõ từng chữ một vào màn hình chat kèm format Markdown đàng hoàng, +So that tôi không phải mòn mỏi nhìn biểu tượng Loading như các web đời cũ. +**Acceptance Criteria:** +**Given** tôi vừa bấm gửi câu hỏi "Ping" +**When** Next.js client mở luồng SSE kết nối về FastAPI +**Then** tin nhắn được append dần lên UI mượt mà với hoạt ảnh <150ms +**And** render được định dạng Markdown cơ bản (Bold, List, Code block) một cách trơn tru, không xộc xệch nhảy dòng khó chịu. + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_web/components/public-chat-snapshots/public-chat-snapshot-row.tsx` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_backend/app/agents/new_chat/checkpointer.py` +- `surfsense_web/components/chat-comments/comment-item/types.ts` +- `surfsense_backend/app/agents/new_chat/tools/google_calendar/create_event.py` +- `surfsense_backend/app/routes/public_chat_routes.py` +- `surfsense_web/components/chat-comments/comment-composer/comment-composer.tsx` +- `surfsense_web/components/public-chat/public-chat-not-found.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/3-3-giao-di-n-khung-chat-ti-p-nh-n-streaming-chat-ui-sse-client.md b/_bmad-output/implementation-artifacts/3-3-giao-di-n-khung-chat-ti-p-nh-n-streaming-chat-ui-sse-client.md deleted file mode 100644 index d43bbc188..000000000 --- a/_bmad-output/implementation-artifacts/3-3-giao-di-n-khung-chat-ti-p-nh-n-streaming-chat-ui-sse-client.md +++ /dev/null @@ -1,31 +0,0 @@ -# Story 3.3: Giao diện Khung Chat & Tiếp nhận Streaming (Chat UI & SSE Client) - -**Status:** done - -## PRD Requirements -As a Người dùng, -I want thấy AI gõ từng chữ một vào màn hình chat kèm format Markdown đàng hoàng, -So that tôi không phải mòn mỏi nhìn biểu tượng Loading như các web đời cũ. -**Acceptance Criteria:** -**Given** tôi vừa bấm gửi câu hỏi "Ping" -**When** Next.js client mở luồng SSE kết nối về FastAPI -**Then** tin nhắn được append dần lên UI mượt mà với hoạt ảnh <150ms -**And** render được định dạng Markdown cơ bản (Bold, List, Code block) một cách trơn tru, không xộc xệch nhảy dòng khó chịu. - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/agents/new_chat/utils.py` -- `surfsense_backend/app/schemas/chat_session_state.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/routes/public_chat_routes.py` -- `surfsense_backend/app/schemas/new_chat.py` -- `surfsense_backend/app/tasks/chat/stream_new_chat.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/3-4-ki-n-tr-c-split-pane-t-ng-t-c-tr-ch-d-n-split-pane-layout-interactive-citation.md b/_bmad-output/implementation-artifacts/3-4-ki-n-tr-c-split-pane-t-ng-t-c-tr-ch-d-n-split-pane-layout-interactive-citation.md deleted file mode 100644 index 4bfcc2583..000000000 --- a/_bmad-output/implementation-artifacts/3-4-ki-n-tr-c-split-pane-t-ng-t-c-tr-ch-d-n-split-pane-layout-interactive-citation.md +++ /dev/null @@ -1,30 +0,0 @@ -# Story 3.4: Kiến trúc Split-Pane & Tương tác Trích dẫn (Split-Pane Layout & Interactive Citation) - -**Status:** done - -## PRD Requirements -As a Người dùng, -I want đọc khung chat ở một bên và văn bản gốc ở bên cạnh trên cùng 1 màn hình, bấm vào thẻ [1] ở chat là bên kia nhảy text tương ứng, -So that tôi có thể đối chiếu thông tin AI "bịa" hay "thật" ngay lập tức mà không phải tìm mỏi mắt. -**Acceptance Criteria:** -**Given** UI chia 2 bên (Split-Pane - bằng react-resizable-panels) - Chat trái, Doc phải (UX-DR3) -**When** AI trả lời xong có đính kèm cite `[1]`, tôi click vào `[1]` -**Then** bảng Document tự động đổi sang file tương ứng và auto-scroll + highlight dải vàng đúng dòng text đó (UX-DR4). - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/3-4-split-pane-layout-interactive-citation.md b/_bmad-output/implementation-artifacts/3-4-split-pane-layout-interactive-citation.md new file mode 100644 index 000000000..b6ad4b34e --- /dev/null +++ b/_bmad-output/implementation-artifacts/3-4-split-pane-layout-interactive-citation.md @@ -0,0 +1,54 @@ +# Story 3.4: Kiến trúc Split-Pane & Tương tác Trích dẫn (Split-Pane Layout & Interactive Citation) + +**Status:** done +**Epic:** Epic 3 +**Story Key:** `3-4-split-pane-layout-interactive-citation` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Người dùng, +I want đọc khung chat ở một bên và văn bản gốc ở bên cạnh trên cùng 1 màn hình, bấm vào thẻ [1] ở chat là bên kia nhảy text tương ứng, +So that tôi có thể đối chiếu thông tin AI "bịa" hay "thật" ngay lập tức mà không phải tìm mỏi mắt. +**Acceptance Criteria:** +**Given** UI chia 2 bên (Split-Pane - bằng react-resizable-panels) - Chat trái, Doc phải (UX-DR3) +**When** AI trả lời xong có đính kèm cite `[1]`, tôi click vào `[1]` +**Then** bảng Document tự động đổi sang file tương ứng và auto-scroll + highlight dải vàng đúng dòng text đó (UX-DR4). + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/3-5-l-a-ch-n-m-h-nh-llm-d-a-tr-n-subscription-model-selection-via-quota.md b/_bmad-output/implementation-artifacts/3-5-model-selection-via-quota.md similarity index 100% rename from _bmad-output/implementation-artifacts/3-5-l-a-ch-n-m-h-nh-llm-d-a-tr-n-subscription-model-selection-via-quota.md rename to _bmad-output/implementation-artifacts/3-5-model-selection-via-quota.md diff --git a/_bmad-output/implementation-artifacts/4-1-chat-history-sync.md b/_bmad-output/implementation-artifacts/4-1-chat-history-sync.md new file mode 100644 index 000000000..83f581e5c --- /dev/null +++ b/_bmad-output/implementation-artifacts/4-1-chat-history-sync.md @@ -0,0 +1,55 @@ +# Story 4.1: Đồng bộ Danh sách Phiên Chat & Lịch sử Tin nhắn (Chat History Sync) + +**Status:** done +**Epic:** Epic 4 +**Story Key:** `4-1-chat-history-sync` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Người dùng, +I want danh sách lịch sử các phiên chat và tin nhắn bên trong tự động đồng bộ xuống máy tôi qua Zero-client, +So that tôi mở app lên là thấy ngay lập tức lịch sử cũ (FR8, FR9) và đọc liên tiếp không cần chờ load từ internet (FR10). +**Acceptance Criteria:** +**Given** thiết bị của tôi đã từng kết nối mạng trước đó +**When** tôi chọn một Session cũ (như hôm qua) trong Sidebar +**Then** hệ thống query trực tiếp từ IndexedDB cục bộ qua thư viện `@rocicorp/zero` và móc lên UI +**And** thời gian data mới từ server đẩy cập nhật xuống dưới Local Storage luôn đảm bảo dưới 3s (NFR-P2). + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/4-1-ng-b-danh-s-ch-phi-n-chat-l-ch-s-tin-nh-n-chat-history-sync.md b/_bmad-output/implementation-artifacts/4-1-ng-b-danh-s-ch-phi-n-chat-l-ch-s-tin-nh-n-chat-history-sync.md deleted file mode 100644 index 09b01733d..000000000 --- a/_bmad-output/implementation-artifacts/4-1-ng-b-danh-s-ch-phi-n-chat-l-ch-s-tin-nh-n-chat-history-sync.md +++ /dev/null @@ -1,31 +0,0 @@ -# Story 4.1: Đồng bộ Danh sách Phiên Chat & Lịch sử Tin nhắn (Chat History Sync) - -**Status:** done - -## PRD Requirements -As a Người dùng, -I want danh sách lịch sử các phiên chat và tin nhắn bên trong tự động đồng bộ xuống máy tôi qua Zero-client, -So that tôi mở app lên là thấy ngay lập tức lịch sử cũ (FR8, FR9) và đọc liên tiếp không cần chờ load từ internet (FR10). -**Acceptance Criteria:** -**Given** thiết bị của tôi đã từng kết nối mạng trước đó -**When** tôi chọn một Session cũ (như hôm qua) trong Sidebar -**Then** hệ thống query trực tiếp từ IndexedDB cục bộ qua thư viện `@rocicorp/zero` và móc lên UI -**And** thời gian data mới từ server đẩy cập nhật xuống dưới Local Storage luôn đảm bảo dưới 3s (NFR-P2). - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/4-2-giao-di-n-ph-n-r-n-h-n-khi-ng-t-m-ng-graceful-degradation-offline-ui.md b/_bmad-output/implementation-artifacts/4-2-giao-di-n-ph-n-r-n-h-n-khi-ng-t-m-ng-graceful-degradation-offline-ui.md deleted file mode 100644 index f0b22ec41..000000000 --- a/_bmad-output/implementation-artifacts/4-2-giao-di-n-ph-n-r-n-h-n-khi-ng-t-m-ng-graceful-degradation-offline-ui.md +++ /dev/null @@ -1,31 +0,0 @@ -# Story 4.2: Giao diện Phân rã Ân hạn khi ngắt mạng (Graceful Degradation Offline UI) - -**Status:** done - -## PRD Requirements -As a Người dùng, -I want hệ thống tự động khóa các tính năng cần internet như "Chat/Gửi tin/Upload" khi tôi mất wifi, -So that tôi không bị văng lỗi hay hiện màn hình đơ cứng, thay vào đó vẫn thong dong đọc nội dung cũ (NFR-R1). -**Acceptance Criteria:** -**Given** người dùng cấu hình ngắt mạng cố ý hoặc đột ngột mất wifi -**When** họ đang mở app -**Then** giao diện tự động bật mode Graceful Degradation: Input chat bị disable, nút Upload file bị mờ (muted xám) -**And** người dùng vẫn có thể click đọc văn bản trên màn Split-Pane thoăn thoắt không trễ (UX-DR6). - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/auth.py` -- `surfsense_backend/app/agents/new_chat/tools/mcp_tool.py` -- `surfsense_backend/app/services/linear/__init__.py` -- `surfsense_backend/app/services/vision_autocomplete_service.py` -- `surfsense_backend/app/etl_pipeline/parsers/vision_llm.py` -- `surfsense_backend/app/agents/new_chat/tools/jira/update_issue.py` -- `surfsense_backend/app/connectors/teams_connector.py` -- `surfsense_backend/app/utils/rbac.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/4-2-graceful-degradation-offline-ui.md b/_bmad-output/implementation-artifacts/4-2-graceful-degradation-offline-ui.md new file mode 100644 index 000000000..cb83322ed --- /dev/null +++ b/_bmad-output/implementation-artifacts/4-2-graceful-degradation-offline-ui.md @@ -0,0 +1,55 @@ +# Story 4.2: Giao diện Phân rã Ân hạn khi ngắt mạng (Graceful Degradation Offline UI) + +**Status:** done +**Epic:** Epic 4 +**Story Key:** `4-2-graceful-degradation-offline-ui` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Người dùng, +I want hệ thống tự động khóa các tính năng cần internet như "Chat/Gửi tin/Upload" khi tôi mất wifi, +So that tôi không bị văng lỗi hay hiện màn hình đơ cứng, thay vào đó vẫn thong dong đọc nội dung cũ (NFR-R1). +**Acceptance Criteria:** +**Given** người dùng cấu hình ngắt mạng cố ý hoặc đột ngột mất wifi +**When** họ đang mở app +**Then** giao diện tự động bật mode Graceful Degradation: Input chat bị disable, nút Upload file bị mờ (muted xám) +**And** người dùng vẫn có thể click đọc văn bản trên màn Split-Pane thoăn thoắt không trễ (UX-DR6). + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/connectors/dropbox/client.py` +- `surfsense_backend/app/schemas/incentive_tasks.py` +- `surfsense_backend/app/utils/proxy_config.py` +- `surfsense_web/components/chat-comments/comment-panel-container/comment-panel-container.tsx` +- `surfsense_web/components/tool-ui/write-todos.tsx` +- `surfsense_web/components/shared/image-config-dialog.tsx` +- `surfsense_backend/app/users.py` +- `surfsense_web/components/ui/dropdown-menu.tsx` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/4-3-global-network-sync-indicators.md b/_bmad-output/implementation-artifacts/4-3-global-network-sync-indicators.md new file mode 100644 index 000000000..e60dbb8c5 --- /dev/null +++ b/_bmad-output/implementation-artifacts/4-3-global-network-sync-indicators.md @@ -0,0 +1,57 @@ +# Story 4.3: Tích hợp Chỉ báo Trạng thái Mạng Toàn Cục (Global Network & Sync Indicators) + +**Status:** done +**Epic:** Epic 4 +**Story Key:** `4-3-global-network-sync-indicators` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +As a Người dùng, +I want thấy một icon nhỏ hoặc dải màu trực quan cho biết App đang Online, Offline, hay Syncing, +So that tôi chủ động biết ứng dụng có đang "sống" và "khớp nối" dữ liệu với đám mây hay không (FR11). +**Acceptance Criteria:** +**Given** app đang khởi chạy bình thường +**When** trạng thái kết nối mạng của Zero Client hoặc Browser thay đổi +**Then** Header hoặc góc dưới màn hình cập nhật icon (Xanh: Connected / Vàng: Syncing / Đỏ/Xám: Offline) +**And** thiết kế phải hòa hợp với bộ màu ZinC/Slate đã chọn, tuyệt đối không dùng thông báo (alert) nhảy ập vào mặt người dùng. +Hệ thống biến từ một ứng dụng tĩnh thành một nền tảng SaaS thương mại thông qua tích hợp thanh toán Stripe. Người dùng có thể xem bảng giá, chọn gói cước phù hợp, thanh toán an toàn và hệ thống tự động kiểm soát quota sử dụng dựa trên gói đăng ký, đảm bảo mô hình kinh doanh bền vững. +**FRs covered:** FR15, FR16, FR17 + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `done`. Implementation should target the following components/files: + +- `surfsense_backend/app/utils/refresh_tokens.py` +- `surfsense_web/app/public/[token]/page.tsx` +- `surfsense_backend/app/routes/circleback_webhook_route.py` +- `surfsense_web/components/TokenHandler.tsx` +- `surfsense_backend/app/schemas/stripe.py` +- `surfsense_backend/app/services/page_limit_service.py` +- `surfsense_web/components/assistant-ui/connector-popup/components/periodic-sync-config.tsx` +- `surfsense_backend/app/services/dropbox/kb_sync_service.py` + +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + diff --git a/_bmad-output/implementation-artifacts/4-3-t-ch-h-p-ch-b-o-tr-ng-th-i-m-ng-to-n-c-c-global-network-sync-indicators.md b/_bmad-output/implementation-artifacts/4-3-t-ch-h-p-ch-b-o-tr-ng-th-i-m-ng-to-n-c-c-global-network-sync-indicators.md deleted file mode 100644 index 6a4375317..000000000 --- a/_bmad-output/implementation-artifacts/4-3-t-ch-h-p-ch-b-o-tr-ng-th-i-m-ng-to-n-c-c-global-network-sync-indicators.md +++ /dev/null @@ -1,33 +0,0 @@ -# Story 4.3: Tích hợp Chỉ báo Trạng thái Mạng Toàn Cục (Global Network & Sync Indicators) - -**Status:** done - -## PRD Requirements -As a Người dùng, -I want thấy một icon nhỏ hoặc dải màu trực quan cho biết App đang Online, Offline, hay Syncing, -So that tôi chủ động biết ứng dụng có đang "sống" và "khớp nối" dữ liệu với đám mây hay không (FR11). -**Acceptance Criteria:** -**Given** app đang khởi chạy bình thường -**When** trạng thái kết nối mạng của Zero Client hoặc Browser thay đổi -**Then** Header hoặc góc dưới màn hình cập nhật icon (Xanh: Connected / Vàng: Syncing / Đỏ/Xám: Offline) -**And** thiết kế phải hòa hợp với bộ màu ZinC/Slate đã chọn, tuyệt đối không dùng thông báo (alert) nhảy ập vào mặt người dùng. -Hệ thống biến từ một ứng dụng tĩnh thành một nền tảng SaaS thương mại thông qua tích hợp thanh toán Stripe. Người dùng có thể xem bảng giá, chọn gói cước phù hợp, thanh toán an toàn và hệ thống tự động kiểm soát quota sử dụng dựa trên gói đăng ký, đảm bảo mô hình kinh doanh bền vững. -**FRs covered:** FR15, FR16, FR17 - -## Architecture Compliance & As-Built Context -> *This section is automatically generated to map implemented components to this story's requirements.* - -This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature: - -- `surfsense_backend/app/schemas/stripe.py` -- `surfsense_backend/app/services/linear/kb_sync_service.py` -- `surfsense_backend/app/services/page_limit_service.py` -- `surfsense_backend/app/services/google_calendar/kb_sync_service.py` -- `surfsense_backend/app/routes/stripe_routes.py` -- `surfsense_backend/app/services/google_drive/kb_sync_service.py` -- `surfsense_backend/app/services/gmail/kb_sync_service.py` -- `surfsense_backend/app/services/onedrive/kb_sync_service.py` - -## Implementation Notes -- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards. -- **Backend**: Needs to follow `surfsense_backend` FastAPI standards. diff --git a/_bmad-output/implementation-artifacts/5-1-giao-di-n-b-ng-gi-l-a-ch-n-g-i-c-c-pricing-plan-selection-ui.md b/_bmad-output/implementation-artifacts/5-1-pricing-plan-selection-ui.md similarity index 100% rename from _bmad-output/implementation-artifacts/5-1-giao-di-n-b-ng-gi-l-a-ch-n-g-i-c-c-pricing-plan-selection-ui.md rename to _bmad-output/implementation-artifacts/5-1-pricing-plan-selection-ui.md diff --git a/_bmad-output/implementation-artifacts/5-2-t-ch-h-p-stripe-checkout-stripe-payment-integration.md b/_bmad-output/implementation-artifacts/5-2-stripe-payment-integration.md similarity index 100% rename from _bmad-output/implementation-artifacts/5-2-t-ch-h-p-stripe-checkout-stripe-payment-integration.md rename to _bmad-output/implementation-artifacts/5-2-stripe-payment-integration.md diff --git a/_bmad-output/implementation-artifacts/5-3-webhook-c-p-nh-t-tr-ng-th-i-g-i-c-c-stripe-webhook-sync.md b/_bmad-output/implementation-artifacts/5-3-stripe-webhook-sync.md similarity index 100% rename from _bmad-output/implementation-artifacts/5-3-webhook-c-p-nh-t-tr-ng-th-i-g-i-c-c-stripe-webhook-sync.md rename to _bmad-output/implementation-artifacts/5-3-stripe-webhook-sync.md diff --git a/_bmad-output/implementation-artifacts/5-4-h-th-ng-kh-a-t-c-v-d-a-tr-n-h-n-m-c-usage-tracking-rate-limit-enforcement.md b/_bmad-output/implementation-artifacts/5-4-usage-tracking-rate-limit-enforcement.md similarity index 100% rename from _bmad-output/implementation-artifacts/5-4-h-th-ng-kh-a-t-c-v-d-a-tr-n-h-n-m-c-usage-tracking-rate-limit-enforcement.md rename to _bmad-output/implementation-artifacts/5-4-usage-tracking-rate-limit-enforcement.md diff --git a/scripts/generate_stories_from_code.py b/scripts/generate_stories_from_code.py index 1e33a7503..1520e4ca2 100644 --- a/scripts/generate_stories_from_code.py +++ b/scripts/generate_stories_from_code.py @@ -26,15 +26,11 @@ def load_sprint_status(): return {} with open(SPRINT_STATUS_FILE, "r") as f: data = yaml.safe_load(f) - if not data or "development_status" not in data: - return {} - return data.get("development_status", {}) def find_related_files(keywords): related = [] - # simplistic scan of app and web - search_dirs = [PROJECT_ROOT / "surfsense_backend" / "app", PROJECT_ROOT / "surfsense_web" / "src"] + search_dirs = [PROJECT_ROOT / "surfsense_backend" / "app", PROJECT_ROOT / "surfsense_web" / "src", PROJECT_ROOT / "surfsense_web" / "components", PROJECT_ROOT / "surfsense_web" / "app"] for sdir in search_dirs: if not sdir.exists(): continue @@ -45,31 +41,24 @@ def find_related_files(keywords): if any(kw in path_str for kw in keywords): rel = os.path.relpath(os.path.join(root, file), PROJECT_ROOT) related.append(rel) - return list(set(related))[:8] # Max 8 files to prevent giant lists + return list(set(related))[:8] def parse_epics(): if not EPICS_FILE.exists(): - print("epics.md not found!") return [] - with open(EPICS_FILE, "r") as f: content = f.read() stories = [] - current_epic_id = None - epic_pattern = re.compile(r'^### Epic (\d+):', re.MULTILINE) story_pattern = re.compile(r'^#### Story ((\d+)\.(\d+)): (.+)', re.MULTILINE) - lines = content.split('\n') current_story = None - + for line in lines: e_match = epic_pattern.match(line) if e_match: - current_epic_id = e_match.group(1) continue - s_match = story_pattern.match(line) if s_match: if current_story: @@ -82,78 +71,114 @@ def parse_epics(): "desc_lines": [] } continue - + if current_story and line.strip() and not line.startswith('#'): current_story["desc_lines"].append(line) if current_story: stories.append(current_story) - return stories -def slugify(text): - text = text.lower() - text = re.sub(r'[^a-z0-9]+', '-', text) - return text.strip('-') - def main(): OUT_DIR.mkdir(parents=True, exist_ok=True) status_map = load_sprint_status() stories = parse_epics() - + + existing_manual_stories = ["3.5", "5.1", "5.2", "5.3", "5.4"] + for s in stories: sid = s["id"] sname = s["name"] status = "backlog/ready-for-dev" sanitized_id = sid.replace('.', '-') + key_found = None for k, v in status_map.items(): if k.startswith(sanitized_id + "-") or k == sanitized_id: status = v + key_found = k break - filename = f"{sanitized_id}-{slugify(sname)}.md" + if not key_found: + continue + + filename = f"{key_found}.md" - # Determine keywords + # We don't overwrite the manually generated ones except to rename them if needed! + # Actually, let's just generate all of them to be clean, BUT wait, user said "ngoài stories 3.5 và epic 5". + # So we skip fully overriding 3.5 and epic 5, but we MIGHT need to rename them. + + # Read old file if exists (using the messy name) to preserve content if we are skipping overriding + # Wait, instead of doing that in python, I'll let python just generate new ones for the "other" stories, + # and I will rename 3.5 and Epic 5 manually. + + if sid in existing_manual_stories: + continue + title_words = sname.lower().split() matched_keywords = set() for dom, kws in DOMAIN_KEYWORDS.items(): if any(w in title_words for w in kws) or any(w in " ".join(s["desc_lines"]).lower() for w in kws): matched_keywords.update(kws) - + if not matched_keywords: matched_keywords = ["main", "app", "index"] - + related_files = find_related_files(matched_keywords) - - # Build Markdown - md = f"# Story {sid}: {sname}\n\n" - md += f"**Status:** {status}\n\n" - md += "## PRD Requirements\n" - md += "\n".join(s["desc_lines"]) + "\n\n" - - md += "## Architecture Compliance & As-Built Context\n" - md += "> *This section is automatically generated to map implemented components to this story's requirements.*\n\n" - if status == "done": - md += "This story has been successfully implemented in the brownfield codebase. The following key files contain the core logic for this feature:\n\n" - else: - md += "This story is currently in the backlog. Implementation should likely integrate with or modify the following files:\n\n" - + + desc_text = "\n".join(s["desc_lines"]) + md = f"""# Story {sid}: {sname} + +**Status:** {status} +**Epic:** Epic {sid.split('.')[0]} +**Story Key:** `{key_found}` + +## 📖 Story Requirements (Context & PRD) +> This section maps directly to the original Product Requirements Document and Epics definition. + +{desc_text} + +## 🏗️ Architecture & Technical Guardrails +> Critical instructions for the development agent based on the project's established architecture. + +### Technical Requirements +- Language/Framework: React, Next.js (TypeScript) for Web; FastAPI (Python) for Backend. +- Database: Prisma/Supabase. +- Strict Type checking must be enforced. No `any` types. + +### Code Organization +This story is currently marked as `{status}`. Implementation should target the following components/files: + +""" if related_files: for f in related_files: md += f"- `{f}`\n" else: - md += "- *No explicit file references found, general application domain applies.*\n" - - md += "\n" - md += "## Implementation Notes\n" - md += "- **UI/UX**: Needs to follow `surfsense_web` React/Tailwind standards.\n" - md += "- **Backend**: Needs to follow `surfsense_backend` FastAPI standards.\n" - + md += "- *Standard application patterns apply. Use `Serena` to locate exact files.*\n" + + md += """ +### Developer Agent Constraints +1. **No Destructive Refactors**: Extend existing modules when possible. +2. **Context Check**: Always refer back to `task.md` and use Context7 to verify latest SDK usages. +3. **BMad Standard**: Update the sprint status using standard metrics. + +## 🧪 Testing & Validation Requirements +- All new endpoints must be tested. +- Frontend components should gracefully degrade. +- Do not introduce regressions into existing user workflows. + +## 📈 Completion Status +*(To be updated by the agent when completing this story)* +- Start Date: _____________ +- Completion Date: _____________ +- Key Files Changed: + - + +""" out_path = OUT_DIR / filename with open(out_path, "w") as out: out.write(md) - + print(f"Generated {filename}") if __name__ == "__main__":