207 lines
7.7 KiB
Markdown
207 lines
7.7 KiB
Markdown
# 森林AI Feature Alignment Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 让前端核心工作流完整使用 `/api/v1`，补齐搜索、项目设置、Inbox 和受控 AI 会话，同时移除伪功能入口。
|
||
|
||
**Architecture:** 前端 API 层只认一种 camelCase DTO，页面事件由 `App` 编排后刷新聚合工作区。后端为搜索和 AI 会话提供独立 registrar；超出 MVP 的入口从页面移除。
|
||
|
||
**Tech Stack:** React、TypeScript、Gin、Gorm、Playwright、Go httptest。
|
||
|
||
## Global Constraints
|
||
|
||
- 所有前端 ID 是 identity 字符串；不兼容 PascalCase 或数字 ID。
|
||
- AI 未经用户确认不得创建任务、笔记或资料。
|
||
- 核心操作必须有 loading、成功反馈和可执行的中文错误。
|
||
- 不实现探索数据源、支付、窗口停靠、自主 Agent 或实时聊天。
|
||
|
||
---
|
||
|
||
### Task 1: 前端 API v1 客户端和错误类型
|
||
|
||
**Files:**
|
||
- Modify: `apps/web_v1/src/api/client.ts`
|
||
- Modify: `apps/web_v1/src/api/projects.ts`
|
||
- Modify: `apps/web_v1/src/api/mappers.tsx`
|
||
- Create: `apps/web_v1/src/api/search.ts`
|
||
- Create: `apps/web_v1/src/api/inbox.ts`
|
||
- Modify: `apps/web_v1/scripts/structure-check.mjs`
|
||
|
||
**Interfaces:**
|
||
- Produces: `ApiError { status: number; code: string; message: string }` and camelCase DTOs only.
|
||
|
||
- [ ] **Step 1: Add failing static checks**
|
||
|
||
Reject `ID?`, `Name?`, `/api/projects`, and `number` project/task IDs in `src/api`. Require `/api/v1` in login and project API paths.
|
||
|
||
- [ ] **Step 2: Verify failures**
|
||
|
||
Run: `node scripts/structure-check.mjs`
|
||
|
||
Expected: FAIL on legacy paths and PascalCase compatibility fields.
|
||
|
||
- [ ] **Step 3: Implement one response contract**
|
||
|
||
Parse the standard error envelope:
|
||
|
||
```ts
|
||
export class ApiError extends Error {
|
||
constructor(public status: number, public code: string, message: string) {
|
||
super(message)
|
||
}
|
||
}
|
||
```
|
||
|
||
All DTOs use required camelCase fields and string IDs. Update date formatting to happen only in mappers.
|
||
|
||
- [ ] **Step 4: Verify frontend types**
|
||
|
||
Run: `node scripts/structure-check.mjs && npm run build && npm run lint`
|
||
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```powershell
|
||
git add apps/web_v1/src/api apps/web_v1/scripts/structure-check.mjs
|
||
git commit -m "refactor(web): consume api v1 contracts"
|
||
```
|
||
|
||
### Task 2: 搜索与项目设置真实往返
|
||
|
||
**Files:**
|
||
- Create: `backend/internal/logic/search/handlers.go`
|
||
- Create: `backend/internal/logic/search/handlers_test.go`
|
||
- Modify: `backend/cmd/api/main.go`
|
||
- Modify: `apps/web_v1/src/pages/projects/project-topbar.tsx`
|
||
- Modify: `apps/web_v1/src/pages/projects/project-sidebar.tsx`
|
||
- Modify: `apps/web_v1/src/app/App.tsx`
|
||
|
||
**Interfaces:**
|
||
- `GET /api/v1/search?q=` returns `{items: SearchResultDTO[]}`.
|
||
- `PATCH /api/v1/projects/:projectId` persists settings and returns ProjectDTO.
|
||
|
||
- [ ] **Step 1: Write failing search handler tests**
|
||
|
||
Assert blank query returns 400 `invalid_query`, authenticated matching query returns project/task/note results, and another user's private objects are absent.
|
||
|
||
- [ ] **Step 2: Verify backend failures**
|
||
|
||
Run: `go test ./internal/logic/search -v`
|
||
|
||
Expected: FAIL because handler is missing.
|
||
|
||
- [ ] **Step 3: Implement search registrar and front-end search state**
|
||
|
||
Topbar accepts `query`, `loading`, `onQueryChange`, `onSearch`. Submit on Enter or the Search button. Render results in an Arco dropdown/list and navigate to the owning project/channel when the result type is known.
|
||
|
||
- [ ] **Step 4: Persist project settings**
|
||
|
||
Replace the local `setWorkspaces`-only update with `updateProject(session, update)`, then call `loadWorkspaces` with the same identity. Keep the modal open on failure.
|
||
|
||
- [ ] **Step 5: Verify**
|
||
|
||
Run: `go test ./internal/logic/search ./internal/logic/projects -v; npm run build; npm run lint`
|
||
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```powershell
|
||
git add backend/internal/logic/search backend/cmd/api/main.go apps/web_v1/src
|
||
git commit -m "feat: connect search and project settings"
|
||
```
|
||
|
||
### Task 3: Inbox 确认流与核心写操作
|
||
|
||
**Files:**
|
||
- Modify: `backend/internal/logic/inbox/handlers.go`
|
||
- Modify: `backend/internal/logic/inbox/service.go`
|
||
- Modify: `backend/internal/logic/inbox/service_test.go`
|
||
- Modify: `apps/web_v1/src/api/inbox.ts`
|
||
- Create: `apps/web_v1/src/pages/projects/project-inbox.tsx`
|
||
- Modify: `apps/web_v1/src/pages/projects/project-channel-page.tsx`
|
||
- Modify: `apps/web_v1/src/app/App.tsx`
|
||
|
||
**Interfaces:**
|
||
- Inbox capture/analyze/confirm uses identity strings.
|
||
- `confirm` accepts only suggestions returned for the same inbox item and current user.
|
||
|
||
- [ ] **Step 1: Add failing identity and authorization tests**
|
||
|
||
Test capture, analyze without writes, confirm selected task/note/source with source Inbox identity, and reject confirming another user's inbox item.
|
||
|
||
- [ ] **Step 2: Verify failures**
|
||
|
||
Run: `go test ./internal/logic/inbox -v`
|
||
|
||
Expected: legacy numeric paths or authorization gaps fail new tests.
|
||
|
||
- [ ] **Step 3: Implement v1 Inbox DTOs and page**
|
||
|
||
The page shows item content, suggestion checkboxes and one `确认创建` action. Analysis results remain drafts until this action. On success refresh the workspace and show the created object count.
|
||
|
||
- [ ] **Step 4: Verify core write operations**
|
||
|
||
Run: `go test ./internal/logic/inbox ./internal/logic/tasks ./internal/logic/projects -v; npm run build; npm run lint`
|
||
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```powershell
|
||
git add backend/internal/logic/inbox apps/web_v1/src
|
||
git commit -m "feat: connect inbox confirmation workflow"
|
||
```
|
||
|
||
### Task 4: 受控 AI 会话与伪功能清理
|
||
|
||
**Files:**
|
||
- Create: `backend/internal/logic/ai/handlers.go`
|
||
- Create: `backend/internal/logic/ai/handlers_test.go`
|
||
- Modify: `backend/internal/logic/ai/sessions.go`
|
||
- Modify: `backend/internal/logic/ai/gateway.go`
|
||
- Modify: `backend/cmd/api/main.go`
|
||
- Modify: `apps/web_v1/src/pages/projects/project-ai.tsx`
|
||
- Modify: `apps/web_v1/src/pages/workspace-explore.tsx`
|
||
- Modify: `apps/web_v1/src/pages/projects/project-new-channel.tsx`
|
||
- Modify: `apps/web_v1/src/pages/projects/project-statusbar.tsx`
|
||
- Modify: `apps/web_v1/src/pages/projects/project-topbar.tsx`
|
||
- Modify: `apps/web_v1/scripts/visual-check.mjs`
|
||
|
||
**Interfaces:**
|
||
- `GET/POST /api/v1/projects/:projectId/ai-sessions` lists/creates controlled sessions.
|
||
- No endpoint converts AI output into formal objects without a separate confirmation request.
|
||
|
||
- [ ] **Step 1: Write failing AI handler tests**
|
||
|
||
Assert session creation checks project ownership, rate limit runs before provider selection, call logs contain required fields, and the response contains no automatic object IDs.
|
||
|
||
- [ ] **Step 2: Verify failures**
|
||
|
||
Run: `go test ./internal/logic/ai -v`
|
||
|
||
Expected: FAIL because handlers are missing.
|
||
|
||
- [ ] **Step 3: Implement controlled session endpoints**
|
||
|
||
Return a session DTO with identity, title, context, status and timestamps. If no provider key exists, return `ai_key_missing` without creating formal objects.
|
||
|
||
- [ ] **Step 4: Remove unsupported controls**
|
||
|
||
Remove active-looking sync/edit/delete actions from Explore, payment choices from the status bar, dock buttons, fake app launcher and nonfunctional channel save. Keep a concise “暂未开放” empty state only where navigation must remain visible.
|
||
|
||
- [ ] **Step 5: Update visual checks and verify**
|
||
|
||
Run: `go test ./...; $env:VISUAL_CHECK_PORT='4174'; node scripts/visual-check.mjs; npm run build; npm run lint`
|
||
|
||
Expected: all PASS, AI page has an `AI 助手` heading, and console errors are empty.
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```powershell
|
||
git add backend/internal/logic/ai backend/cmd/api/main.go apps/web_v1/src apps/web_v1/scripts/visual-check.mjs
|
||
git commit -m "feat: align controlled AI sessions and MVP controls"
|
||
```
|
||
|