senlinai/agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0ca2898ac0229590888fb24b03fe0f526491bcb7
agent/docs/superpowers/specs/2026-07-21-senlinai-mvp-unification-design.md

14 KiB
Raw Blame History

森林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、开发配置、演示数据和全量验证。
Reference in New Issue View Git Blame Copy Permalink