docs: update forest AI setup and verification

2026-07-21 21:23:21 +08:00
parent 7f71c971eb
commit fff6cdcba7
2 changed files with 336 additions and 104 deletions
--- a/docs/mvp-verification.md
+++ b/docs/mvp-verification.md
@@ -1,101 +1,213 @@
-# MVP Verification
+# 森林AI MVP 验证

-## Backend
+本文记录 2026-07-21 在 Windows、PowerShell 环境中对当前仓库实际执行的验证。只有获得成功退出码或明确 HTTP 响应的命令列为通过；未满足环境条件的项目单独列出，不视为通过。

-Run:
+## 环境基线
+
+- Go `1.26.1 windows/amd64`
+- Node.js `24.11.0`
+- npm `11.12.1`
+- Rust `1.97.1`
+- Cargo `1.97.1`
+- Docker CLI：当前机器不可用
+- `DATABASE_URL`：当前 shell 未设置
+
+本地 Compose 与 `backend/etc/agent.dev.yaml` 约定 PostgreSQL 监听 `localhost:5432`，API 监听 `localhost:9150`，Vite 默认监听 `localhost:5173`。Compose 和开发配置中的固定数据库凭据只供本地开发，生产环境必须替换。
+
+## 本次结果摘要
+
+| 验证项 | 结果 | 说明 |
+| --- | --- | --- |
+| `go test ./...` | 通过 | 全部 Go 包通过；另以 `-count=1` 无缓存复核通过。 |
+| `go run ./cmd/api` | 未通过 | 本机现有 PostgreSQL 的账号配置与开发配置不匹配，初始化时认证失败。 |
+| `go run ./cmd/seed` | 未通过 | 与 API 相同，因本机 PostgreSQL 认证失败。 |
+| Compose 启动 | 未验证 | 当前机器没有可用的 Docker CLI，未声称启动成功。 |
+| Web 依赖安装 | 通过 | `npm ci` 成功，审计未发现漏洞。 |
+| Web 短时启动 | 通过 | `npm run dev` 启动；因默认端口已有用户进程，占用时自动选择可用端口，HTTP 根路径返回 `200`。本次进程随后已停止。 |
+| Web 视觉检查 | 通过 | `node scripts/visual-check.mjs` 退出 `0`，无未预期 console error。 |
+| Web 生产构建 | 通过 | `npm run build` 退出 `0`；存在 bundle 大小警告，不影响构建结果。 |
+| Web lint | 通过 | `npm run lint` 退出 `0`。 |
+| Web 结构检查 | 通过 | `node scripts/structure-check.mjs` 输出 `structure ok`。 |
+| 桌面端依赖安装 | 通过 | `apps/desktop` 下 `npm ci` 成功。 |
+| Tauri 可执行文件构建 | 通过 | 冷构建超过单次 240 秒工具等待上限，但已完成 release 编译；同一命令增量重跑 58.3 秒退出 `0`。 |
+| Tauri 安装包 | 未验证 | 本次未运行 `npm run bundle`。 |
+| PostgreSQL 集成测试 | 未运行 | 当前 shell 未提供 `DATABASE_URL`。 |
+
+## 本地启动检查
+
+### PostgreSQL
+
+需要 Docker Desktop。仓库根目录的预期命令是：
+
+```powershell
+docker compose -f infra/docker-compose.yml up -d
+docker compose -f infra/docker-compose.yml ps
+```
+
+当前机器无法识别 `docker` 命令，因此这两条命令未验证。不要根据本记录推断 Compose 已成功启动。
+
+### 演示数据与 API
+
+数据库可用后，在两个独立终端中运行：

 ```powershell
 Set-Location backend
-go test ./... -v
+go run ./cmd/seed
 ```

-Expected: all backend tests pass.
+```powershell
+Set-Location backend
+go run ./cmd/api
+```

-## PostgreSQL Integration
-
-Set `DATABASE_URL` to the live PostgreSQL test database before running integration checks. Do not commit real credentials.
-
-Run:
+本次两条命令都真实执行过，但均在连接本机 PostgreSQL 时因开发账号认证失败而退出。排除本机数据库冲突并成功启动后，应检查：

 ```powershell
+Invoke-RestMethod http://localhost:9150/healthz
+Invoke-RestMethod http://localhost:9150/api/v1/status
+```
+
+预期分别返回 `status: ok` 和 UTC RFC 3339 `timestamp`。`/api/v1/status` 是登录页使用的公开连接检查；其他业务接口除登录外均要求有效 bearer 会话。
+
+### Web 开发服务器
+
+```powershell
+Set-Location apps/web_v1
+npm ci
+npm run dev
+```
+
+本次 `npm ci` 通过。短时启动时默认端口已被用户原有 Vite 进程占用，本次实例自动选择另一个可用端口；对该实例根路径请求得到 HTTP `200`。验证结束后仅停止了本次新建的进程树，用户原有进程未被修改。
+
+## 自动化验证
+
+### 后端
+
+```powershell
+Set-Location backend
+go test ./...
+```
+
+本次退出 `0`。为排除 Go 测试缓存影响，还执行了：
+
+```powershell
+go test -count=1 ./...
+```
+
+无缓存复核同样退出 `0`，覆盖配置、HTTP 路由、认证、项目/工作区、任务、标签、资料、Inbox、关键词搜索、AI key 加密、限流与审计等包。
+
+### PostgreSQL 集成测试
+
+仅在准备了隔离的实时测试数据库时运行：
+
+```powershell
+$env:DATABASE_URL='<隔离测试库连接串>'
 Set-Location backend
 go test -tags integration ./internal/models -run TestPostgresPing -v
 ```

-Expected: `TestPostgresPing` passes.
+连接串必须通过安全的本地或 CI secret 注入，不能提交到仓库。本次 `DATABASE_URL` 未设置，因此没有运行，也不列为通过。

-## Web
-
-The primary frontend is the React + Arco Design client under `apps/web_v1`.
-
-Run:
+### Web

 ```powershell
 Set-Location apps/web_v1
 node scripts/visual-check.mjs
 npm run build
 npm run lint
+node scripts/structure-check.mjs
 ```

-Expected: visual smoke checks, production build, and lint pass.
+四条命令本次均退出 `0`。视觉检查覆盖桌面和移动登录页、工作台、项目导航、Inbox 确认、AI 会话受控创建、深色模式、无横向溢出和无未预期 console error。

-## Desktop
+`npm run build` 生成：

-Run:
+- `apps/web_v1/dist/index.html`
+- `apps/web_v1/dist/assets/`
+- `apps/web_v1/dist/senlinai-icon.svg`
+
+`node scripts/visual-check.mjs` 生成的本地证据位于 `apps/web_v1/test-results/`，包括：
+
+- `login-react-acro.png`
+- `login-react-acro-mobile.png`
+- `workbench-react-acro-light.png`
+- `project-react-acro-light.png`
+- `project-react-acro-dark.png`
+- `project-navigation-mobile.png`
+- `channel-navigation-mobile.png`
+- `project-inbox-confirmed.png`
+- `project-inbox-confirmed-mobile.png`
+- `project-ai-controlled.png`
+
+`dist/` 与 `test-results/` 都是本地产物，已被 `.gitignore` 排除，不应提交。
+
+### 桌面端

 ```powershell
-Set-Location apps/web_v1
-npm run build
-Set-Location ../desktop
+Set-Location apps/desktop
+npm ci
 npm run build
 ```

-Expected: the Tauri desktop executable builds when Rust/Cargo is installed and the stable Rust toolchain is complete.
+本次最终重跑退出 `0`。`npm run build` 使用 `tauri build --no-bundle`，并先执行 Web 生产构建。Windows 可执行文件为：

-Installer packaging is a separate step:
+```text
+apps/desktop/src-tauri/target/release/senlinai_workbench.exe
+```
+
+本次产物大小为 `8,783,360` 字节。冷构建需要下载或编译 Rust 依赖，可能耗时数分钟；本次第一次调用因外部等待工具达到 240 秒上限而返回超时，但编译日志已显示 release 完成和产物生成，随后相同命令增量重跑获得退出码 `0`。
+
+安装包是独立验证项：

 ```powershell
 Set-Location apps/desktop
 npm run bundle
 ```

-Current machine status:
- Cargo and rustc are installed under `%USERPROFILE%\.cargo\bin`.
- If the current shell does not see Cargo yet, prepend `%USERPROFILE%\.cargo\bin` to `PATH` or open a new terminal.
- `npx tauri build --no-bundle --verbose` passes and produces `apps/desktop/src-tauri/target/release/senlinai_workbench.exe`.
- Full installer bundling through `npm run bundle` currently times out in the Tauri CLI bundling stage on this machine before producing `target/release/bundle` artifacts.
+本次没有运行该命令，不记录安装包结果。

-## Latest Audit Verification
+## API 契约抽查

-Last audited: 2026-07-18.
+当前路由注册与 Web API client 均使用 `/api/v1`：

- `backend`: `go test ./... -v` passed.
- `apps/web_v1`: `node scripts/visual-check.mjs` passed.
- `apps/web_v1`: `npm run build` passed.
- `apps/web_v1`: `npm run lint` passed.
- `apps/desktop`: `npx tauri build --no-bundle --verbose` passed and produced the desktop executable.
- `apps/desktop`: installer packaging is still blocked by Tauri CLI bundling timeout on the current machine.
+- 公共：`GET /api/v1/status`、`POST /api/v1/auth/login`。
+- 项目与工作区：项目列表/创建/读取/更新，以及项目工作区读取。
+- 任务与标签：任务创建/更新、项目标签列表/创建。
+- 资料与计划任务：multipart 文件资料创建、计划任务元数据创建。
+- Inbox：收集、生成建议、按服务端建议 ID 确认。
+- 搜索：带 `q` 参数的关键词搜索，响应为 `items` 数组。
+- AI 会话：项目会话列表与受控创建，响应为会话 DTO。

-Audit fixes included:
+抽查结论：创建接口返回 `201`，读取和当前更新接口返回 `200`；JSON DTO 使用 camelCase，对外路径参数使用 UUIDv7，错误为 `error.code` 与 `error.message` 包装结构。API 不直接返回 Gorm 模型或内部自增 ID。

- Signed expiring auth session tokens replaced forgeable `user:<id>` tokens.
- Project and inbox HTTP handlers now read the authenticated user from bearer middleware instead of hard-coding user `1`.
- Project dashboard loading now checks project ownership before returning counters.
- Inbox confirmation preserves provenance with `source_inbox_item_id` on generated tasks, notes, and sources.
- Task sharing now rejects note/source links from another project.
- AI user keys are encrypted before storage, decrypted on selection, and can be checked with a per-user action rate limit.
- Web API calls use the backend `/api` prefix, and the active client is now the React + Arco Design workbench.
+## 人工 MVP 流程

-## Manual MVP Flow
+在 Compose、seed、API 和 Web 均成功启动后，按以下顺序人工验收：

-1. Open the client and enter the server IP or domain on the login screen.
-2. Create or log in as a private-deployment user.
-3. Create a project.
-4. Add text to project inbox.
-5. Click Analyze/Organize.
-6. Confirm one task and one note from the suggestion list.
-7. Assign the task to another system user.
-8. Explicitly share one note with the task.
-9. Search for text from the note body in global search.
-10. Open an AI session under the project and reference the note.
-11. Use Tauri quick capture to send text into the active project inbox.
+1. 打开 Web 客户端，在登录页输入服务器 IP 地址或域名。
+2. 使用仅供开发的演示账号登录，并确认生产部署未使用默认凭据。
+3. 创建项目，修改项目设置，再刷新确认数据保留。
+4. 创建项目内标签和任务，验证任务卡显示真实标签与状态。
+5. 上传文件资料，确认返回路径是相对存储路径，且越权项目不能留下文件。
+6. 创建计划任务元数据，确认界面没有暗示自主 Agent 已执行。
+7. 收集一条 Inbox 内容，先分析建议；此时不应出现正式对象。
+8. 选择一条或多条服务端建议并确认，验证生成对象保留来源 Inbox ID。
+9. 用关键词搜索项目、任务和笔记，确认用户只能看到有权访问的结果。
+10. 创建项目 AI 会话，确认缺 key、限流和服务错误有明确提示，且不会自动生成正式对象。
+11. 在桌面与移动视口检查项目/频道导航、焦点状态和横向溢出。
+12. 启动桌面可执行文件，逐项检查登录持久化、拖拽上传、通知和全局快捷收集等 MVP 目标；未实际走通的能力不得记为通过。
+
+## 安全复核清单
+
+- 生产环境已替换数据库凭据、`auth_secret`、AI key 加密密钥和所有开发默认值。
+- 未提交数据库连接串、用户 AI key、会话凭据、日志、数据库文件、上传文件或构建产物。
+- 登录凭据由签名且会过期的 bearer session 校验，handler 从认证上下文获取用户。
+- 用户 AI key 加密存储；AI 操作在 key/provider 选择前占用限流配额，并写 provider、key 类型、action、status 和 error 审计。
+- AI 输出只形成待确认草稿；用户确认前不创建任务、笔记或资料。
+- 项目标签保持项目内范围；任务分享的 note/source 与任务属于同一项目。
+- 被指派人只看到任务和明确分享的关联对象。
+- PostgreSQL 集成测试只使用显式 `DATABASE_URL` 指向的隔离测试库。
+
+## 文档一致性检查
+
+已对两份文档执行旧品牌、旧 API 前缀、旧前端目录和旧技术栈关键词扫描，结果无匹配。还应抽查 Markdown 相对链接存在，所有命令的工作目录与仓库实际脚本一致。