306 lines
14 KiB
Markdown
306 lines
14 KiB
Markdown
# 森林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. 数据与配置
|
||
|
||
- 保留 `sa_` 表名前缀和 `Sa` 模型前缀。
|
||
- 本地开发数据允许清空后通过 `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、开发配置、演示数据和全量验证。
|
||
|