# 森林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、开发配置、演示数据和全量验证。

