diff --git a/README.md b/README.md index a410b85..0ff5457 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ The product centers on support tickets and business knowledge, with configurable ## Current Status -Active implementation. The project has a runnable Django + React baseline with enterprise governance, shadcn-based frontend foundation, Docker Compose local startup, category-driven ticket workflows, and reusable solution adoption for fast ticket closure. +Active implementation. The project has a runnable Django + React baseline with enterprise governance, shadcn-based frontend foundation, Docker Compose local startup, category-driven ticket workflows, reusable solution adoption for fast ticket closure, and a knowledge base and retrieval baseline. Key docs: diff --git a/docs/frontend/design-system.md b/docs/frontend/design-system.md index c6cbb2c..63b3281 100644 --- a/docs/frontend/design-system.md +++ b/docs/frontend/design-system.md @@ -71,6 +71,8 @@ Business pages should use: - Ticket status transitions use `TicketTransitionDialog`. Resolution and closure actions can carry a solution summary; non-resolution workflow actions still require a handling note. - Ticket workflows are category-driven: business and operation issues support short closure paths, data issues use a medium path, and technical issues keep the standard support workflow. - Linked solutions support search, recommendation-only linking, adoption with automatic ticket closure, and prefilled resolution text during later resolve/close actions. +- Knowledge pages use the same `AppPage`, `AppSection`, `AppDataTable`, `AppField`, and shadcn form primitives as ticket and system pages. +- Knowledge search results must show source type, title, score, and citable content snippets. - System governance quick-create forms use `AppSection`, `FieldGroup`, and `AppField`. Preview page: diff --git a/docs/superpowers/plans/2026-07-03-stage-2-knowledge-vector-retrieval.md b/docs/superpowers/plans/2026-07-03-stage-2-knowledge-vector-retrieval.md index 4e2f2a4..826db27 100644 --- a/docs/superpowers/plans/2026-07-03-stage-2-knowledge-vector-retrieval.md +++ b/docs/superpowers/plans/2026-07-03-stage-2-knowledge-vector-retrieval.md @@ -57,7 +57,7 @@ Docs: - Modify: `backend/config/settings/base.py` - Modify: `backend/config/urls.py` -- [ ] **Step 1: Write failing CRUD tests** +- [x] **Step 1: Write failing CRUD tests** Create `backend/apps/knowledge/tests/test_knowledge_api.py`: @@ -133,7 +133,7 @@ def test_ingest_document_text_creates_document_and_chunks(admin_client, db): assert KnowledgeChunk.objects.filter(document=document).count() >= 1 ``` -- [ ] **Step 2: Run tests to verify RED** +- [x] **Step 2: Run tests to verify RED** Run: @@ -143,7 +143,7 @@ python -m pytest backend\apps\knowledge\tests\test_knowledge_api.py -v Expected: fails because `apps.knowledge` and `/api/knowledge/*` routes do not exist. -- [ ] **Step 3: Create models** +- [x] **Step 3: Create models** Create `backend/apps/knowledge/models.py`: @@ -258,7 +258,7 @@ class KnowledgeChunk(models.Model): ] ``` -- [ ] **Step 4: Register app and router** +- [x] **Step 4: Register app and router** Create `backend/apps/knowledge/apps.py`: @@ -299,7 +299,7 @@ from apps.knowledge.api import router as knowledge_router api.add_router("/knowledge", knowledge_router) ``` -- [ ] **Step 5: Add schemas** +- [x] **Step 5: Add schemas** Create `backend/apps/knowledge/schemas.py`: @@ -373,7 +373,7 @@ class KnowledgeItemOut(Schema): updated_at: datetime ``` -- [ ] **Step 6: Implement CRUD API** +- [x] **Step 6: Implement CRUD API** Create `backend/apps/knowledge/api.py`: @@ -459,7 +459,7 @@ def create_knowledge_document(request, payload: KnowledgeDocumentIn): ) ``` -- [ ] **Step 7: Create migrations** +- [x] **Step 7: Create migrations** Run: @@ -470,7 +470,7 @@ python manage.py makemigrations knowledge Expected: creates `backend/apps/knowledge/migrations/0001_initial.py`. -- [ ] **Step 8: Verify GREEN** +- [x] **Step 8: Verify GREEN** Run: @@ -481,7 +481,7 @@ python -m ruff check backend\apps\knowledge backend\config Expected: CRUD tests pass and ruff has no issues. -- [ ] **Step 9: Commit** +- [x] **Step 9: Commit** Run: @@ -501,7 +501,7 @@ git commit -m "feat: add knowledge base core api" - Modify: `backend/apps/knowledge/api.py` - Modify: `backend/apps/solutions/api.py` -- [ ] **Step 1: Write failing retrieval tests** +- [x] **Step 1: Write failing retrieval tests** Create `backend/apps/knowledge/tests/test_retrieval.py`: @@ -561,7 +561,7 @@ def test_published_solution_can_be_indexed_for_retrieval(db): assert chunks[0].metadata["solution_id"] == solution.id ``` -- [ ] **Step 2: Run tests to verify RED** +- [x] **Step 2: Run tests to verify RED** Run: @@ -571,7 +571,7 @@ python -m pytest backend\apps\knowledge\tests\test_retrieval.py -v Expected: fails because retrieval services do not exist. -- [ ] **Step 3: Implement chunking and embedding services** +- [x] **Step 3: Implement chunking and embedding services** Create `backend/apps/knowledge/services.py`: @@ -733,7 +733,7 @@ def retrieve_knowledge(query: str, knowledge_base_id: int | None = None, limit: ] ``` -- [ ] **Step 4: Add retrieval schemas and API** +- [x] **Step 4: Add retrieval schemas and API** Append to `backend/apps/knowledge/schemas.py`: @@ -771,7 +771,7 @@ def search_knowledge(request, payload: KnowledgeSearchIn): ) ``` -- [ ] **Step 5: Index published solutions on create** +- [x] **Step 5: Index published solutions on create** Modify `backend/apps/solutions/api.py` in `create_solution`: @@ -794,7 +794,7 @@ if solution.status == "published": return solution ``` -- [ ] **Step 6: Verify GREEN** +- [x] **Step 6: Verify GREEN** Run: @@ -805,7 +805,7 @@ python -m ruff check backend\apps\knowledge backend\apps\solutions Expected: tests pass and ruff has no issues. -- [ ] **Step 7: Commit** +- [x] **Step 7: Commit** Run: @@ -827,7 +827,7 @@ git commit -m "feat: add knowledge retrieval service" - Modify: `frontend/src/app/router.tsx` - Modify: `frontend/src/components/app/AppSidebar.tsx` -- [ ] **Step 1: Create frontend types** +- [x] **Step 1: Create frontend types** Create `frontend/src/features/knowledge/types.ts`: @@ -866,7 +866,7 @@ export type KnowledgeSearchResult = { } ``` -- [ ] **Step 2: Create frontend API** +- [x] **Step 2: Create frontend API** Create `frontend/src/features/knowledge/api.ts`: @@ -910,7 +910,7 @@ export function searchKnowledge(query: string, knowledgeBaseId?: number) { } ``` -- [ ] **Step 3: Create knowledge base list page** +- [x] **Step 3: Create knowledge base list page** Create `frontend/src/features/knowledge/KnowledgeBaseListPage.tsx` using `AppPage`, `AppPageHeader`, `AppSection`, `AppDataTable`, `AppField`, `Input`, and `Button`. @@ -929,7 +929,7 @@ Required Chinese UI: The quick-create form posts to `createKnowledgeBase`, reloads `listKnowledgeBases`, and clears the form. -- [ ] **Step 4: Create knowledge item editor** +- [x] **Step 4: Create knowledge item editor** Create `frontend/src/features/knowledge/KnowledgeItemEditorPage.tsx` using existing `AppField`, `Input`, `Textarea`, `Select`, `SelectGroup`, and `Button`. @@ -963,7 +963,7 @@ Required Chinese sections: On success, navigate to `#/knowledge/search`. -- [ ] **Step 5: Create knowledge search page** +- [x] **Step 5: Create knowledge search page** Create `frontend/src/features/knowledge/KnowledgeSearchPage.tsx` using `AppPage`, `AppPageHeader`, `AppSection`, `Input`, `Button`, `Badge`, and `Card`. @@ -991,7 +991,7 @@ Required Chinese UI: 暂无检索结果 ``` -- [ ] **Step 6: Wire routes** +- [x] **Step 6: Wire routes** Modify `frontend/src/app/router.tsx`: @@ -1013,7 +1013,7 @@ if (route === '/knowledge/search') { } ``` -- [ ] **Step 7: Add sidebar navigation** +- [x] **Step 7: Add sidebar navigation** Modify `frontend/src/components/app/AppSidebar.tsx` to add Chinese knowledge menu entries under the existing navigation group: @@ -1024,7 +1024,7 @@ Modify `frontend/src/components/app/AppSidebar.tsx` to add Chinese knowledge men Use lucide icons already available in `lucide-react`. -- [ ] **Step 8: Verify frontend** +- [x] **Step 8: Verify frontend** Run: @@ -1035,7 +1035,7 @@ npm run build Expected: both commands pass. -- [ ] **Step 9: Commit** +- [x] **Step 9: Commit** Run: @@ -1053,7 +1053,7 @@ git commit -m "feat: add knowledge management pages" - Modify: `docs/frontend/design-system.md` - Modify: `docs/superpowers/plans/2026-07-03-stage-2-knowledge-vector-retrieval.md` -- [ ] **Step 1: Run backend verification** +- [x] **Step 1: Run backend verification** Run: @@ -1071,7 +1071,7 @@ all selected tests pass All checks passed! ``` -- [ ] **Step 2: Run frontend verification** +- [x] **Step 2: Run frontend verification** Run: @@ -1082,7 +1082,7 @@ npm run build Expected: TypeScript and Vite build succeed. -- [ ] **Step 3: Run database migration locally** +- [x] **Step 3: Run database migration locally** Run: @@ -1093,7 +1093,7 @@ python manage.py migrate Expected: `knowledge.0001_initial` is applied. -- [ ] **Step 4: Update README current status** +- [x] **Step 4: Update README current status** Modify `README.md` current status sentence to include: @@ -1101,7 +1101,7 @@ Modify `README.md` current status sentence to include: knowledge base and retrieval baseline ``` -- [ ] **Step 5: Update frontend design system** +- [x] **Step 5: Update frontend design system** Modify `docs/frontend/design-system.md` under `Current Core Screens`: @@ -1110,11 +1110,11 @@ Modify `docs/frontend/design-system.md` under `Current Core Screens`: - Knowledge search results must show source type, title, score, and citable content snippets. ``` -- [ ] **Step 6: Mark plan complete** +- [x] **Step 6: Mark plan complete** In this plan file, mark completed task checkboxes as `[x]` after successful execution. -- [ ] **Step 7: Commit** +- [x] **Step 7: Commit** Run: @@ -1127,16 +1127,16 @@ git commit -m "docs: sync stage 2 knowledge progress" ## Final Review Checklist -- [ ] `apps.knowledge` exists and is registered in Django settings. -- [ ] Knowledge bases can be created and listed through API. -- [ ] Knowledge items create chunks. -- [ ] Document text ingestion creates chunks. -- [ ] Published solutions can be indexed as knowledge chunks. -- [ ] Retrieval returns citable chunk results with source metadata. -- [ ] Frontend has Chinese knowledge base, item creation, and search pages. -- [ ] Sidebar exposes knowledge navigation. -- [ ] Backend tests pass. -- [ ] Backend ruff passes. -- [ ] Frontend typecheck passes. -- [ ] Frontend build passes. -- [ ] README and design-system docs reflect Stage 2 behavior. +- [x] `apps.knowledge` exists and is registered in Django settings. +- [x] Knowledge bases can be created and listed through API. +- [x] Knowledge items create chunks. +- [x] Document text ingestion creates chunks. +- [x] Published solutions can be indexed as knowledge chunks. +- [x] Retrieval returns citable chunk results with source metadata. +- [x] Frontend has Chinese knowledge base, item creation, and search pages. +- [x] Sidebar exposes knowledge navigation. +- [x] Backend tests pass. +- [x] Backend ruff passes. +- [x] Frontend typecheck passes. +- [x] Frontend build passes. +- [x] README and design-system docs reflect Stage 2 behavior.