docs: update forest AI setup and verification

README.md

@@ -1,76 +1,143 @@
-# SenlinAI Agent Workbench
+# 森林AI
 
-SenlinAI Agent Workbench 是一个以项目为中心的私有化工作台 MVP。
+## 产品定位
 
-## 本地开发
+森林AI 是一个以项目为中心、面向私有化部署的工作台 MVP，服务于个人知识工作者、团队负责人和可信的内部用户。它把项目、任务、Inbox 收集、Markdown 笔记、文件资料、AI 会话、项目内标签和轻量任务分发组织在同一工作区中。
 
-启动本地 PostgreSQL：
+Web 客户端桌面优先，同时保留移动浏览器可用性；登录页允许输入私有部署服务器的 IP 地址或域名。
+
+## MVP 范围
+
+当前版本包含：
+
+- 项目创建、设置和聚合工作区。
+- 项目内任务、标签、文件资料和计划任务元数据。
+- Inbox 收集、分析建议和用户确认创建对象的流程。
+- 项目、任务和笔记的关键词搜索。
+- 项目内 AI 会话入口、密钥选择、限流与调用审计。
+- React Web 客户端和 Tauri 桌面壳。
+
+当前版本不包含实时即时通讯、项目级成员角色体系、匿名公开分享、自主 Agent 执行、语义或向量搜索、第三方数据源集成、原生移动 App、浏览器扩展、离线编辑或本地优先同步。
+
+## 技术栈
+
+- 后端：Go 1.26.1、Gin、Gorm、PostgreSQL 16。
+- Web：React 18、TypeScript、Vite 8、Arco Design。
+- 桌面端：Tauri 2、Rust stable，共用 Web 构建产物。
+- 本地基础设施：Docker Compose。
+
+本仓库当前验证环境使用 Node.js 24.11.0、npm 11.12.1、Rust 1.97.1；其他版本应满足各锁文件与工具链要求。
+
+## 目录结构
+
+```text
+.
+├── backend/                  # Go API、数据库模型、业务逻辑和演示数据
+│   ├── cmd/api/              # API 入口
+│   ├── cmd/seed/             # 开发演示数据入口
+│   ├── etc/                  # 按模式加载的 YAML 配置
+│   └── internal/             # httpx、models 与各业务包
+├── apps/web_v1/              # React + TypeScript 主 Web 客户端
+├── apps/desktop/             # Tauri 桌面壳
+├── infra/docker-compose.yml  # 本地 PostgreSQL 16
+└── docs/                     # 规格、计划与 MVP 验证说明
+```
+
+## 快速开始
+
+### 1. 准备环境
+
+安装 Go、Node.js/npm 和 Docker Desktop，并确保 Docker Desktop 已启动。桌面端构建还需要 Rust stable 与平台编译工具链。
+
+### 2. 启动 PostgreSQL
+
+在仓库根目录运行：
 
 ```powershell
 docker compose -f infra/docker-compose.yml up -d
 ```
 
-启动后端 API：
+Compose 只用于本地开发，创建 PostgreSQL 16 服务并监听 `localhost:5432`。其中的默认数据库凭据不得用于生产环境。
+
+### 3. 初始化演示数据
+
+```powershell
+Set-Location backend
+go run ./cmd/seed
+```
+
+默认演示账号为 `demo@senlin.ai`，默认密码为 `password123`。它们只用于本地开发；生产部署必须创建正式用户并替换所有默认凭据与密钥。
+
+### 4. 启动 API
+
+在新的终端中运行：
 
 ```powershell
 Set-Location backend
 go run ./cmd/api
 ```
 
-启动 Web 客户端：
+开发配置默认监听 `http://localhost:9150`。可用 `GET /healthz` 检查进程健康状态；Web 登录页使用 `GET /api/v1/status` 检查服务器连接。
+
+### 5. 启动 Web 客户端
+
+在新的终端中运行：
 
 ```powershell
 Set-Location apps/web_v1
+npm ci
 npm run dev
 ```
 
-## 后端配置
+Vite 默认地址为 `http://localhost:5173`。登录时服务器地址填写 `http://localhost:9150`；也可以通过 `VITE_API_BASE_URL` 指定 Web 的初始 API 地址。
 
-后端配置不再从多个环境变量直接读取，而是从 `backend/etc/agent.<mode>.yaml` 读取。
+## 配置
 
-配置模式由环境变量 `SENLIN_APP_MODE` 决定：
+后端从 `backend/etc/agent.<mode>.yaml` 读取配置。`SENLIN_APP_MODE` 未设置时使用 `backend/etc/agent.dev.yaml`；例如设置 `$env:SENLIN_APP_MODE='prod'` 时读取 `backend/etc/agent.prod.yaml`，该生产文件需由部署方安全提供。
 
-- 未设置 `SENLIN_APP_MODE` 时，默认读取 `backend/etc/agent.dev.yaml`。
-- 设置 `SENLIN_APP_MODE=prod` 时，读取 `backend/etc/agent.prod.yaml`。
-- 设置其他值时，按同样规则读取 `backend/etc/agent.<value>.yaml`。
+| 字段 | 用途 |
+| --- | --- |
+| `env` | 运行环境标识。 |
+| `port` | API 监听端口；开发值为 `9150`。 |
+| `dsn` | PostgreSQL 连接串。 |
+| `storage_dir` | 服务端文件存储根目录。 |
+| `max_upload_bytes` | multipart 请求体大小上限；开发值为 32 MiB。 |
+| `auth_secret` | 邀请和登录会话签名密钥。 |
+| `system_ai_key` | 可选的系统级 AI provider fallback key。 |
+| `ai_key_encryption_secret` | 用户 AI key 的静态加密密钥。 |
+| `allowed_origins` | 允许访问 API 的 Web/Tauri 来源列表。 |
 
-默认开发配置文件：
+不要提交生产数据库连接串、AI key、会话凭据或真实密钥。开发配置中的固定值和 Compose 数据库账号仅供本地使用，生产环境必须全部替换。修改 Web 来源或端口时，应同步更新 `allowed_origins`，否则浏览器会拦截跨域请求。
 
-```text
-backend/etc/agent.dev.yaml
-```
+`go run ./cmd/seed` 还支持 `DATABASE_DSN` 或 `DATABASE_URL` 临时覆盖数据库地址，以及 `SENLIN_SEED_EMAIL`、`SENLIN_SEED_NAME`、`SENLIN_SEED_PASSWORD` 覆盖演示用户信息。
 
-配置字段：
+## API v1 概览
 
-- `env`: 运行环境，例如 `development`。
-- `port`: API 监听端口，默认开发值为 `8080`。
-- `dsn`: PostgreSQL 连接串。不要提交真实生产或测试凭据。
-- `storage_dir`: 服务端本地文件存储目录。
-- `auth_secret`: 邀请 token 和 session token 的 HMAC 密钥。
-- `system_ai_key`: 可选的系统级 AI provider fallback key。
-- `ai_key_encryption_secret`: 用户 AI key 静态加密密钥。
+业务接口前缀为 `/api/v1`，JSON 字段使用 camelCase，对外 ID 使用 UUIDv7 字符串，时间使用 UTC RFC 3339。除连接状态和登录外，接口都要求有效的 `Authorization: Bearer` 会话凭据。
 
-## 前端
+| 方法 | 路径 | 成功响应 |
+| --- | --- | --- |
+| `GET` | `/api/v1/status` | `200`，包含 `timestamp` 的对象；无需登录。 |
+| `POST` | `/api/v1/auth/login` | `200`，包含签名且会过期的 `token` 字段；请求体为 `email`、`password`。 |
+| `GET` | `/api/v1/projects` | `200`，项目 DTO 数组。 |
+| `POST` | `/api/v1/projects` | `201`，项目 DTO。 |
+| `GET` | `/api/v1/projects/:projectId` | `200`，项目 DTO。 |
+| `PATCH` | `/api/v1/projects/:projectId` | `200`，更新后的项目 DTO。 |
+| `GET` | `/api/v1/projects/:projectId/workspace` | `200`，聚合项目、频道、标签、Inbox、任务、AI 会话、笔记资料和计划任务的工作区 DTO。 |
+| `POST` | `/api/v1/projects/:projectId/tasks` | `201`，任务 DTO。 |
+| `PATCH` | `/api/v1/projects/:projectId/tasks/:taskId` | `200`，更新后的任务 DTO。 |
+| `GET` | `/api/v1/projects/:projectId/tags` | `200`，该项目的标签 DTO 数组。 |
+| `POST` | `/api/v1/projects/:projectId/tags` | `201`，标签 DTO。 |
+| `POST` | `/api/v1/projects/:projectId/sources` | `201`，文件资料 DTO；请求为含 `file` 和可选 `title` 的 multipart 表单。 |
+| `POST` | `/api/v1/projects/:projectId/cron-plans` | `201`，计划任务 DTO；只管理元数据，不执行自主 Agent。 |
+| `POST` | `/api/v1/projects/:projectId/inbox` | `201`，Inbox 条目 DTO。 |
+| `POST` | `/api/v1/inbox/:inboxId/analyze` | `200`，`suggestions` 草稿数组，不创建正式对象。 |
+| `POST` | `/api/v1/inbox/:inboxId/confirm` | `200`，含 `createdCount`；只确认服务端已保存且由用户选中的建议。 |
+| `GET` | `/api/v1/search?q=...` | `200`，`items` 数组，当前检索项目、任务和笔记。 |
+| `GET` | `/api/v1/projects/:projectId/ai-sessions` | `200`，AI 会话 DTO 数组。 |
+| `POST` | `/api/v1/projects/:projectId/ai-sessions` | `201`，AI 会话 DTO；请求体只接收 `title`、`context`。 |
 
-Web 客户端使用 React、TypeScript、Vite 和 Arco Design。登录界面允许用户输入服务器 IP 地址或域名，并将其保存为 API base URL。
-
-## 桌面端
-
-桌面端使用 Tauri 包装 Web 客户端。
-
-构建桌面可执行文件：
-
-```powershell
-Set-Location apps/desktop
-npm run build
-```
-
-生成安装包：
-
-```powershell
-Set-Location apps/desktop
-npm run bundle
-```
+错误统一返回 `{"error":{"code":"...","message":"..."}}`。路径中的项目、任务和 Inbox ID 必须是 UUIDv7；数据库自增 ID 不对外暴露。
 
 ## 验证
 
@@ -78,7 +145,7 @@ npm run bundle
 
 ```powershell
 Set-Location backend
-go test ./... -v
+go test ./...
 ```
 
 Web：
@@ -90,11 +157,64 @@ npm run build
 npm run lint
 ```
 
-桌面端：
+如果设置了指向隔离测试库的 `DATABASE_URL`，再运行 PostgreSQL 集成检查：
+
+```powershell
+Set-Location backend
+go test -tags integration ./internal/models -run TestPostgresPing -v
+```
+
+不得把真实测试数据库凭据写入仓库。当前机器的逐项执行结果与产物路径见 [MVP 验证说明](docs/mvp-verification.md)。
+
+## 桌面端
+
+先完成 Web 依赖安装，再构建 Tauri 可执行文件：
 
 ```powershell
 Set-Location apps/desktop
+npm ci
 npm run build
 ```
 
-更多验证说明见 `docs/mvp-verification.md`。
+`npm run build` 会先执行 Web 生产构建，再运行 `tauri build --no-bundle`。Windows 产物位于 `apps/desktop/src-tauri/target/release/senlinai_workbench.exe`。
+
+需要安装包时运行：
+
+```powershell
+Set-Location apps/desktop
+npm run bundle
+```
+
+打包需要 Rust stable、平台编译工具链和对应安装器依赖；它与无安装包的可执行文件构建是两个独立验证项。
+
+## 常见问题
+
+### 数据库连接或认证失败
+
+确认 Docker Desktop 和 Compose 服务正在运行，并用 `docker compose -f infra/docker-compose.yml ps` 查看状态。若本机已有 PostgreSQL 占用 `5432`，请停止冲突服务或同步修改 Compose 映射与 `backend/etc/agent.dev.yaml` 中的 `dsn`。演示数据和 API 必须连接到同一个数据库。
+
+### 浏览器提示无法连接或 CORS 错误
+
+先访问 `http://localhost:9150/api/v1/status`。如果 API 可达但浏览器仍失败，检查登录页的服务器地址、协议和端口，并把实际 Web 来源加入 `allowed_origins` 后重启 API。
+
+### Vite 端口被占用
+
+默认端口是 `5173`。可以停止占用进程，或让 Vite 选择可用端口；使用其他端口时必须同步配置后端 `allowed_origins`。
+
+### 演示账号无法登录
+
+先成功运行 `go run ./cmd/seed`，再使用 seed 命令输出所对应的开发账号。若通过环境变量覆盖过演示用户信息，应使用覆盖后的值。生产环境不得使用默认演示密码。
+
+### AI 会话返回缺少密钥或限流错误
+
+创建 AI 会话前会执行每用户、每动作限流并选择加密存储的用户 key 或系统 fallback key。缺少可用 key 时返回服务不可用，超过配额时返回 `429`；不要在前端或提交记录中粘贴 key。
+
+## 安全说明
+
+- 登录会话使用签名且会过期的 bearer token；服务端从认证中间件读取当前用户，不接受可伪造的用户 ID 字符串。
+- 用户 AI key 加密存储。AI 操作先限流，再选择 provider/key，并记录 provider、key 类型、action、status 和 error；日志不得记录 key 明文。
+- AI 分析和会话不会自动创建正式任务、笔记或资料。Inbox 只有在用户确认服务端保存的建议后才创建对象，并保留来源 Inbox ID。
+- 项目标签只在项目内有效。任务移动、标签写入和文件上传都校验项目所有权。
+- 任务分享遵循最小可见范围：被指派人只能看到任务以及被显式分享的关联对象；分享的 note/source 必须与任务属于同一项目。
+- 文件存储路径只由文件服务构造，上传在写磁盘前校验所有权和请求体大小。
+- 生产部署必须替换所有开发凭据和密钥、限制 CORS 来源、使用独立数据库与受控存储目录，并通过 HTTPS 暴露服务。