From ea69d509a631523cd10ba0a7c896df8a400acaf4 Mon Sep 17 00:00:00 2001
From: yanweidong <david.yan@qq.com>
Date: Tue, 21 Jul 2026 12:19:56 +0800
Subject: [PATCH] docs: define forest AI MVP unification

---
 ...6-07-21-senlinai-mvp-unification-design.md | 305 ++++++++++++++++++
 1 file changed, 305 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-21-senlinai-mvp-unification-design.md

diff --git a/docs/superpowers/specs/2026-07-21-senlinai-mvp-unification-design.md b/docs/superpowers/specs/2026-07-21-senlinai-mvp-unification-design.md
new file mode 100644
index 0000000..074cf20
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-21-senlinai-mvp-unification-design.md
@@ -0,0 +1,305 @@
+# 森林AI MVP 统一重构设计
+
+## 1. 背景与目标
+
+当前仓库已经具备项目工作台 MVP 的主要页面、数据模型和部分 API，但品牌、前端体验、API 契约、后端职责边界和开发文档尚未形成一致体系。本次重构允许调整既有 API 和开发数据结构，不要求向后兼容；目标是得到一个可启动、可验证、结构清晰的“森林AI”MVP。
+
+本设计覆盖：
+
+- 使用已确认的森林AI SVG ICON 替换前端品牌占位图形。
+- 页面标题和产品文案统一为“森林AI”。
+- 系统整理前端配色、字体、布局、响应式行为和文案。
+- 重新定义前后端 API 契约并打通 MVP 核心操作。
+- 拆分后端过大的模块，明确职责，并补充有价值的中文注释。
+- 更新 README、开发启动配置和验证说明。
+
+本设计不引入实时聊天、项目角色体系、匿名公开分享、自主 Agent、语义/向量搜索、支付、第三方数据源集成、原生移动 App 或浏览器扩展。
+
+## 2. 现状审计
+
+审计基于 2026-07-21 本地运行的真实页面，桌面视口为 1440×1024，移动视口为 390×844。证据保存在 `apps/web_v1/test-results/audit-current/`，该目录仅用于本地审计，不提交到仓库。
+
+### 2.1 登录页
+
+- 三栏登录卡片在 1440px 宽度下已经裁切右侧内容。
+- “森林Agent”“SenlinAI”“AI Agent”同时出现，品牌命名不一致。
+- 服务器连接检测可工作，但错误恢复路径和说明不够清晰。
+- 登录卡片承载了过多营销式内容，与私有部署入口的主要任务竞争。
+
+### 2.2 全局工作台
+
+- 项目轨道、搜索和聚合任务的结构清晰，可以保留。
+- 页面下半部分空白过多，卡片密度和信息节奏不均衡。
+- 品牌仍使用字母 `S` 占位。
+- 状态栏包含固定展示数据，并存在 `<button>` 嵌套 `<button>` 的无效 DOM。
+
+### 2.3 项目概览与频道
+
+- 项目侧栏的信息架构清楚，但项目横幅色彩过强，压过了主要内容。
+- `实时接口`、固定进度等文案没有提供真实状态含义。
+- 已存在的项目标签没有稳定显示在任务卡片上。
+- AI 智能体页面缺少视觉检查所要求的标题。
+- 多个可见按钮没有行为，包括搜索、资料排序、探索同步、AI 发送、频道保存和部分工具栏动作。
+
+### 2.4 移动端
+
+- `@media (max-width: 1180px)` 仍强制工作台 `min-width: 1180px`。
+- 390px 视口只显示桌面布局左侧切片，主内容不可正常访问。
+- 当前实现不满足“桌面优先，同时保持移动浏览器可用”的项目要求。
+
+### 2.5 API 与后端
+
+- CORS 允许端口以硬编码列表存在，审计端口 4176 被拒绝，开发配置容易漂移。
+- 列表接口、创建接口和工作区 DTO 同时存在 Go 默认 PascalCase 与手写 camelCase 响应。
+- 前端为项目类型兼容两种大小写字段，但其他类型没有一致策略。
+- `projects/service.go` 超过 800 行，混合项目写入、任务、标签、工作区查询、格式化和用户解析。
+- `projects/handlers.go` 超过 360 行，重复当前用户、路径参数、请求绑定和错误响应逻辑。
+- `search`、`ai`、`notes` 和 `tasks` 中已有部分服务，但并未完整注册为前端可用接口。
+- `backend/internal` 几乎没有说明业务边界的注释。
+
+## 3. 总体方案
+
+采用“森林AI MVP 统一版”：
+
+1. 保留现有 React + TypeScript + Vite + Arco Design 技术栈和工作台信息架构。
+2. 建立统一品牌资产和前端设计令牌，修复桌面与移动布局。
+3. API 迁移到 `/api/v1`，只提供 camelCase DTO，对外使用 UUIDv7 identity。
+4. 后端按业务职责拆分 handler、service 和 DTO，不直接向 API 返回 Gorm 模型。
+5. 仅打通 MVP 核心能力；对超出范围的可见控件移除、禁用或提供明确说明。
+6. 开发数据库允许重建，但程序不得自动删除生产数据。
+
+## 4. 品牌资产
+
+### 4.1 ICON
+
+ICON 遵循 `docs/superpowers/specs/2026-07-21-senlinai-icon-design.md`：
+
+- 无文字 SVG，`viewBox="0 0 128 128"`。
+- 森林蓝圆角方形，主色 `#165DFF`。
+- 白色树冠融合年轮、知识层次和脑回路。
+- 青绿与浅蓝节点表达 AI 和知识连接。
+- 不使用渐变、滤镜、字体或外部资源。
+
+正式源文件为 `apps/web_v1/public/senlinai-icon.svg`。`favicon.svg` 使用同一图形。登录页、顶部品牌区和项目轨道工作台按钮均引用该文件，不复制内联 SVG。
+
+### 4.2 命名
+
+- HTML `<title>`：`森林AI`。
+- 产品可见名称：`森林AI`。
+- 英文域名、包名和内部标识可继续使用 `senlinai`。
+- 不再出现 `森林Agent`、`SenlinAI Workbench` 或以字母 `S` 作为品牌图形。
+- `AI智能体` 统一写作 `AI 助手`，避免暗示自主执行能力。
+
+## 5. 前端体验设计
+
+### 5.1 设计令牌
+
+在独立的主题样式文件中集中维护：
+
+- 主色：`#165DFF`。
+- 浅色背景、面板、边框、主文字、次要文字和状态色。
+- 深色主题使用同名语义令牌，不在组件中散落另一套品牌色。
+- 间距使用 4、8、12、16、24、32px 尺度。
+- 控件圆角以 6–8px 为主，项目头像可使用更明显圆角。
+
+字体使用系统中文字体栈：`-apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif`。正文保持 14px 基准，辅助文字 12px，页面标题 24–28px，不随视口连续缩放。
+
+### 5.2 登录页
+
+- 桌面使用品牌说明 + 登录表单双栏，不再使用会被裁切的三栏结构。
+- 服务器地址位于首位，保留连接状态和重新检查。
+- 登录失败显示可执行的中文错误信息。
+- 移动端改为单栏，品牌说明压缩到表单上方。
+- 隐私政策和服务协议在没有实际页面时不显示为伪链接。
+
+### 5.3 工作台布局
+
+- 桌面保留 96px 项目轨道和 248px 项目频道侧栏。
+- 1180px 以下将频道侧栏改为抽屉或可收起面板。
+- 768px 以下隐藏常驻项目轨道，使用顶部导航按钮打开项目与频道抽屉。
+- 主内容始终占满剩余宽度，不设置强制桌面 `min-width`。
+- 底部状态栏在移动端精简，仅保留真实状态；修复嵌套按钮。
+
+### 5.4 页面与文案
+
+- 工作台概览压缩无意义空白，保留项目、未完成任务、AI 会话和知识资料四项真实指标。
+- 项目横幅使用项目色作为小面积强调，不使用整块高饱和背景压制内容。
+- 删除 `实时接口`、固定 `进度 60%`、固定存储空间等假状态。
+- 任务卡显示后端真实标签、状态、负责人、截止时间和创建时间。
+- 搜索框连接关键词搜索接口。
+- 项目设置连接项目更新接口。
+- 创建项目、任务、标签、资料和计划任务继续使用真实 API。
+- Inbox 使用收集、分析建议、用户确认创建对象的现有安全流程。
+- AI 助手保留会话列表和受控请求入口；未经确认不创建正式对象。
+
+### 5.5 不支持控件
+
+以下功能不在本次 MVP 中实现：探索数据源同步、第三方连接、升级支付、窗口停靠、真实频道外链管理和自主 Agent。对应控件应移除，或在必须保留入口时明确显示“暂未开放”，不得表现为可成功执行的操作。
+
+### 5.6 可访问性
+
+- 每个图标按钮有可访问名称。
+- 页面使用正确的标题层级、`main`、`nav` 和 `aside` 语义。
+- 键盘可完成登录、项目切换、频道切换、搜索和核心表单提交。
+- 焦点状态清晰，错误不只依赖颜色。
+- 交互目标最小 40×40px；小型状态标签不承担点击行为。
+- 自动化检查不能证明完整 WCAG 合规，仍需键盘和辅助技术人工复核。
+
+## 6. API 设计
+
+### 6.1 通用约定
+
+- 前缀：`/api/v1`。
+- JSON 字段：camelCase。
+- 对外 ID：模型 UUIDv7 `identity` 字段，序列化为字符串。
+- 时间：RFC 3339 UTC；显示格式由前端处理。
+- 成功状态码：读取 200，创建 201，无响应体更新 204。
+- 错误格式：`{"error":{"code":"invalid_request","message":"请求参数无效"}}`。
+- bearer session token 继续由认证中间件校验，handler 从上下文获取当前用户。
+
+### 6.2 公共接口
+
+- `GET /api/v1/status`
+- `POST /api/v1/auth/login`
+
+### 6.3 项目与工作区
+
+- `GET /api/v1/projects`
+- `POST /api/v1/projects`
+- `GET /api/v1/projects/:projectId`
+- `PATCH /api/v1/projects/:projectId`
+- `GET /api/v1/projects/:projectId/workspace`
+
+工作区响应聚合项目、频道计数、标签、Inbox、任务、AI 会话、笔记资料和计划任务，供首屏一次加载。
+
+### 6.4 任务与标签
+
+- `POST /api/v1/projects/:projectId/tasks`
+- `PATCH /api/v1/projects/:projectId/tasks/:taskId`
+- `GET /api/v1/projects/:projectId/tags`
+- `POST /api/v1/projects/:projectId/tags`
+
+任务响应使用同一 Task DTO，创建与更新接口不得返回数据库模型。任务移动到另一项目时重新校验所有权，并清理不属于目标项目的标签。
+
+### 6.5 资料、计划任务与 Inbox
+
+- `POST /api/v1/projects/:projectId/sources`
+- `POST /api/v1/projects/:projectId/cron-plans`
+- `POST /api/v1/projects/:projectId/inbox`
+- `POST /api/v1/inbox/:inboxId/analyze`
+- `POST /api/v1/inbox/:inboxId/confirm`
+
+文件路径只由文件服务生成。Inbox 确认创建的对象继续保存来源 Inbox identity。
+
+### 6.6 搜索与 AI
+
+- `GET /api/v1/search?q=...`
+- `GET /api/v1/projects/:projectId/ai-sessions`
+- `POST /api/v1/projects/:projectId/ai-sessions`
+
+AI provider 请求必须先经过限流和密钥选择，随后记录 provider、key 类型、action、status 和 error。前端不得把 AI 结果直接保存为正式任务、笔记或资料。
+
+## 7. 后端结构
+
+继续遵守 `backend/internal/logic` 业务包规则和 `backend/internal/models` 模型集中规则。
+
+### 7.1 `httpx`
+
+- `router.go`：路由装配和中间件。
+- `response.go`：统一成功与错误响应。
+- `params.go`：identity 路径参数和分页/查询参数解析。
+- CORS 从配置读取允许来源；开发默认值与 Vite 默认端口一致。
+
+### 7.2 `projects`
+
+- `service.go`：项目创建、读取和更新。
+- `workspace.go`：只负责工作区聚合查询。
+- `dto.go`：项目和工作区响应 DTO。
+- `handlers.go`：项目与工作区 HTTP 接口。
+- `ownership.go`：项目所有权查询与复用校验。
+
+### 7.3 其他业务包
+
+- `tasks`：任务 CRUD、指派和显式分享。
+- `files`：文件保存路径和资料记录。
+- `inbox`：收集、建议和确认。
+- `search`：关键词搜索 handler 与 service。
+- `ai`：会话、密钥、限流和调用审计。
+- `notes`：笔记服务保持聚焦；没有前端写入需求时不新增多余接口。
+
+### 7.4 中文注释
+
+中文注释覆盖：
+
+- 导出的业务接口和 DTO 的用途。
+- 认证、所有权、任务分享、Inbox 确认和 AI 调用的安全边界。
+- identity 与内部自增 ID 的转换原因。
+- 工作区聚合和非显然查询的设计意图。
+
+不对简单赋值、普通条件判断或显而易见的 CRUD 步骤堆砌注释。
+
+## 8. 数据与配置
+
+- 保留 `senlin_agent_` 表名前缀和 `SenlinAgent` 模型前缀。
+- 本地开发数据允许清空后通过 `go run ./cmd/seed` 重建。
+- 代码不得在启动时自动 drop 表或删除生产数据。
+- Docker Compose、`agent.dev.yaml` 和 README 使用一致的 PostgreSQL 用户、密码、数据库名和端口。
+- PostgreSQL 集成测试继续从 `DATABASE_URL` 读取实时测试数据库 URL。
+- CORS 允许来源通过配置项表达，默认覆盖 Vite 开发地址和 Tauri 地址。
+- `.superpowers/`、运行日志、审计截图和本地文件存储目录不提交。
+
+## 9. README
+
+README 使用 UTF-8 中文并包含：
+
+- 森林AI 产品定位和 MVP 边界。
+- 技术栈与目录结构。
+- 环境要求和一套可复制的本地启动步骤。
+- 数据库初始化与演示数据命令。
+- 配置文件与敏感信息说明。
+- `/api/v1` 核心接口概览。
+- 后端、前端和桌面端验证命令。
+- 常见启动问题：数据库连接、CORS、端口冲突和登录凭据。
+
+## 10. 错误处理与状态
+
+- 前端 API client 解析统一错误 DTO，并向用户显示中文消息。
+- 网络不可达、401、403、404、409 和 500 使用不同文案。
+- 所有异步写操作显示 loading，成功后刷新对应工作区数据。
+- 空项目、空任务、空资料和空搜索结果使用明确的下一步说明。
+- 后端内部错误写日志，但响应不泄露数据库、路径或密钥细节。
+
+## 11. 验证与验收
+
+### 11.1 后端
+
+- `go test ./...` 通过。
+- handler 契约测试断言 camelCase DTO、identity 参数和标准错误结构。
+- 项目所有权、跨项目任务移动、标签范围、分享范围、文件路径和 AI 限流均有测试。
+- 如提供 `DATABASE_URL`，PostgreSQL 集成测试通过。
+
+### 11.2 前端
+
+- `node scripts/visual-check.mjs` 通过，无 console error。
+- `npm run build` 通过。
+- `npm run lint` 通过。
+- 1440×1024 登录、工作台、项目概览和任务页截图无裁切或横向溢出。
+- 390×844 登录和项目页可访问主内容，导航可打开与关闭。
+- 页面 `<title>` 为“森林AI”，品牌位置均使用正式 ICON。
+- 搜索、项目设置、创建项目、任务、标签、资料和计划任务完成真实 API 往返。
+
+### 11.3 文档与提交
+
+- README 中的启动和验证命令与仓库实际脚本一致。
+- 每个实施任务创建一个聚焦提交。
+- 不提交真实凭据、本地数据库、运行日志、审计临时文件或构建产物。
+
+## 12. 实施顺序
+
+1. 品牌 ICON、标题、设计令牌和前端基础语义。
+2. 登录页与响应式工作台布局。
+3. `/api/v1` 通用契约、identity 参数与项目/工作区接口。
+4. 任务、标签、资料、计划任务、Inbox、搜索和 AI 会话接口对齐。
+5. 后端文件拆分、中文注释和契约测试补齐。
+6. README、开发配置、演示数据和全量验证。
+