fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/brainstorms/2026-06-29-bitable-ui-compl...

13 KiB
Raw Blame History

date topic
2026-06-29 bitable-ui-completeness

多维表格 UI 完善需求文档

Summary

引入"多维表格文件"作为最上级容器，重构 文件 → 数据表 → 字段/记录 三层骨架，按飞书/twenty 范式补齐表内字段操作、默认字段、select 编辑器、多视图、三类采集入口、公式编辑器、权限/自动化/表单等能力。分四阶段交付，阶段一聚焦文件层 + 默认字段 + 表内字段操作三件事。当前无现有 bitable 数据需迁移，数据模型变更成本可控。

Problem Frame

AgentKit 多维表格（bitable）后端 v1 已基本齐全：领域模型（表/字段/记录/视图/公式）+ REST API（表/字段/记录/视图/upsert/上传/公式校验）+ 异步重算 worker + 三类采集引擎（Excel/数据库/API）+ 公式解析器全部就位。但前端 UI 层薄、产品形态残缺，导致"功能不完善，无法正常使用"。

三类核心缺口：

  1. 层级缺失：当前只有"数据表"层，缺最上级的"多维表格文件"容器。飞书（多维表格 App → 数据表）和 twenty（Object → 记录）都有这个上层归集，bitable 当前是平铺的表列表，数据无组织归属。
  2. 默认字段缺失：新建数据表是空表起步，没有自带默认字段集。飞书/twenty 新建表都自带"标题/状态/日期/创建人/创建时间"等基础字段，让用户立即有结构可填。
  3. 表内字段操作缺失：增/改/删字段只能通过右侧"字段管理"弹层，不能在表内列头直接操作。飞书/twenty 都支持点列头下拉菜单管理字段。

此外 select/multiselect 字段编辑器仍是文本输入（不是下拉选项），三类采集入口在前端无 UI，ViewType 枚举有 5 种但前端只实现 grid 一种，公式编辑器只有校验 API 没有 UI 增强。

现状是"后端能力齐备，前端产品形态不到位"。本次完善的目标是把前端产品形态对齐飞书/twenty 范式，让 bitable 真正可用。

Key Decisions

KD1. 方案选 Approach 1：飞书范式复刻，三层容器骨架先行。 不选 Approach 2（表内体验优先 + 文件层轻量化后置）也不选 Approach 3（Agent 数据底座优先）。理由：用户明确"全面对齐飞书/twenty"，A2 的轻量文件层会在权限/共享/自动化能力上撞天花板，A3 偏离了"参照飞书"的诉求。

KD2. 文件层一次到位引入新实体，不接受轻量化分组方案。 文件层是数据组织基石，延后做会让前期数据无归属、后期二次迁移更痛。当前 schema V1（create_all 模式），无现有 bitable 数据需迁移，引入文件层是干净的新增。

KD3. 分四阶段执行。 阶段一（文件层骨架 + 默认字段 + 表内字段操作 + select 编辑器）→ 阶段二（三类采集入口 + Agent 写入反馈）→ 阶段三（看板/画廊视图 + 公式编辑器增强）→ 阶段四（权限 + 自动化 + 表单 + 甘特）。每阶段可独立验证交付。

KD4. 默认字段集参照飞书 5 字段：标题（text）/ 状态（select）/ 日期（date）/ 创建人（user）/ 创建时间（datetime）。 不做可配置模板，固定集即可。后续若需按用途类型预设模板，再评估。

KD5. 视觉决策用文字探讨，不开浏览器探针。 用户选择文字描述选项，所有布局/交互形态决策通过文字对话确认。

KD6. 保留原需求文档"自建 + 底座心智"方向。 文件层天然可作为 Agent 持久化结构化数据底座的承载点，未来 Agent 写入就是写入文件内的表。原方向不冲突。

KD7. Agent 集成放阶段二，不在阶段一。 阶段一聚焦用户主动建表体验，阶段二再做 Agent 采集闭环与写入反馈。理由：阶段一的产品形态不完整时做 Agent 集成会让 Agent 写入落到错误的结构上。

Actors

  • 用户：数据精修者与分析者。在落地后的表上编辑用户列、配置视图、做分析。本次完善的主要服务对象。
  • Agent：数据作者。执行三类采集（Excel/数据库/API），按字段写入多维表格。阶段二开始接入 UI 反馈。
  • 伴生服务：bitable 自有 API/CLI、自有领域模型、自有存储边界。AgentKit ↔ bitable 走 API/CLI，不做进程内紧耦合。

Requirements

阶段一：文件层骨架与表内基础体验

R1. 引入"多维表格文件"作为最上级容器，数据表归属文件。文件自有元数据（名称/图标/描述等），支持 CRUD。

R2. 新建数据表自带默认字段集，参照飞书 5 字段：标题（text）、状态（select，预设"未开始/进行中/已完成"3 选项）、日期（date）、创建人（user）、创建时间（datetime）。

R3. 表内字段操作走列头下拉菜单。支持重命名、改类型、隐藏、删除。不再依赖右侧"字段管理"弹层作为唯一入口。

R4. select/multiselect 字段编辑器使用下拉选项（带颜色标签），替换当前文本输入。选项在字段配置中维护。

R5. 三层导航层级：文件列表 → 文件详情（含多张表）→ 表内（字段/记录/视图）。文件列表是新的最上级入口，替代当前平铺的表列表。

阶段二：三类采集入口与 Agent 写入反馈

R6. Excel 上传采集入口：前端 UI 触发，调用已有 src/agentkit/bitable/ingestion/excel.py 后端。用户上传 Excel 文件或提供 URL，按字段写入指定表的"数据列"，保留"用户列"。

R7. 数据库导入采集入口：前端 UI 触发，调用已有 src/agentkit/bitable/ingestion/database.py 后端。用户指定数据库连接与表，生成对应多维表格。

R8. API/爬虫采集入口：前端 UI 触发，调用已有 src/agentkit/bitable/ingestion/api_collector.py 后端。用户配置 API 端点或爬虫指令，Agent 执行采集后按字段写入。

R9. Agent 写入反馈 UI：用户能看见 Agent 最近写入的记录与写入历史。形态在 Outstanding Questions 中确认。

阶段三：多视图与公式编辑器增强

R10. 看板视图：按分组字段（通常是 select 字段）分列展示记录卡片，支持拖拽卡片改分组。

R11. 画廊视图：以图片/附件字段为主视觉的卡片网格展示。

R12. 公式编辑器增强：函数提示、字段引用插入、实时语法校验。复用已有 POST /api/v1/bitable/fields/validate-formula 端点。

阶段四：权限、自动化、表单、甘特

R13. 文件级与表级权限模型。文件可共享给用户/部门，表继承文件权限并可细化。

R14. 自动化触发器：事件（记录新增/字段变更/定时）→ 动作（写另一字段/发通知/调 API）。

R15. 表单视图：以表单形式收集数据写入指定表。表单可分享链接。

R16. 甘特视图：按日期字段排时间线，支持依赖关系连线。

Key Flows

  • F1. 用户建表流程

    • Trigger: 用户点"新建文件"按钮
    • Actors: 用户
    • Steps: 创建文件（命名/选图标）→ 在文件内点"新建表" → 表自带 5 个默认字段 → 用户在表内点列头加新字段（如"邮箱"）→ 配置字段类型与选项
    • Outcome: 文件含 1 张带默认字段+用户扩展字段的表

  • F2. Agent 采集写入流程

    • Trigger: 用户在文件内点"采集数据"按钮
    • Actors: 用户、Agent、伴生服务
    • Steps: 选采集类型（Excel/DB/API）→ 配置采集参数 → Agent 执行采集 → 按主键 upsert 写入指定表 → UI 显示 Agent 写入反馈（新记录高亮/写入历史）
    • Outcome: 表内有 Agent 写入的数据列，用户的列与公式列保留不变

  • F3. 表内字段操作流程

    • Trigger: 用户在表内点某列列头
    • Actors: 用户
    • Steps: 列头下拉菜单弹出 → 选"重命名/改类型/隐藏/删除" → 执行操作 → 表实时更新
    • Outcome: 字段状态变更，不需要打开右侧字段管理弹层

Acceptance Examples

  • AE1. 新建文件"销售管线"

    • Covers R1, R2, R3, R5.
    • Given 用户在文件列表页
    • When 点"新建文件"命名"销售管线" → 进入文件详情 → 点"新建表"命名"客户"
    • Then 表自带 5 个默认字段（标题/状态/日期/创建人/创建时间）→ 用户点"标题"列头下拉 → 选"重命名"改为"公司名" → 表头实时更新

  • AE2. Agent 采集 Excel 写入

    • Covers R6, R9.
    • Given 用户在"客户"表内已加"邮箱"用户列
    • When 点"采集数据" → 选 Excel 上传 → 选一份客户名单 Excel → Agent 写入
    • Then 表内出现新记录（数据列被填充）→ "邮箱"用户列保持不变 → UI 显示"Agent 写入 N 条"反馈

  • AE3. 切换看板视图

    • Covers R10.
    • Given "客户"表内有"状态"select 字段（未开始/进行中/已完成）
    • When 点 ViewSwitcher → 新建看板视图 → 分组字段选"状态"
    • Then 表渲染为三列看板（未开始/进行中/已完成）→ 拖拽某卡片从"未开始"到"进行中" → 该记录的"状态"字段自动改为"进行中"

Success Criteria

  • 阶段一验收：用户能创建文件、新建表自带默认字段、表内直接增改删字段、select 下拉编辑器可用、三层导航层级清晰。
  • 整体完成：四阶段全部交付，UI 体验对齐飞书/twenty 范式（三层骨架 + 多视图 + 采集 + 公式编辑器 + 权限/自动化/表单）。
  • 后端兼容：现有 v1 后端 API 不被破坏。文件层引入是新增 schema（V2），不破坏现有 V1 表结构。
  • E2E 覆盖：每阶段交付时 e2e 测试覆盖关键流程（建表/采集/视图切换/字段操作）。当前 e2e/bitable-view.spec.ts 仅 B1/B2 两个基础测试，需扩展。

Scope Boundaries

本次范围内

四阶段全部 16 个 R（R1-R16）。

延后（v3 范围）

  • 多人实时协作（多人同时编辑同一表，光标/选区同步）
  • 大规模优化（列式存储、分区、物化视图、异步重算管道升级）

本产品身份之外

  • 通用电子表格：bitable 是字段化记录模型，不是单元格自由编辑
  • ETL/数据管道平台：采集是 Agent 驱动的按需执行，非定时调度管道
  • BI 仪表盘产品：分析能力服务于表格内聚合，非独立 BI
  • 知识库 RAG 替代：bitable 是结构化数据载体，非非结构化文档检索

Dependencies / Assumptions

  • 依赖：现有后端 v1 齐全（src/agentkit/bitable/{service,repository,models,recalc_worker,db,formula,ingestion}），本次完善主要在前端 + 后端加文件层新实体。
  • 依赖：vxe-table 4 已用于 BitableGrid，继续作为 grid 实现基础。
  • 依赖：Ant Design Vue 4 + Vue 3 + Pinia + TypeScript（强类型，禁 any）。
  • 假设：现有 PostgreSQL 性能足以支撑 v1/v2 规模。
  • 假设：文件层引入只需 schema V2 升级（当前 V1，create_all 模式，无 alembic 迁移）。
  • 假设：用户接受分阶段交付，每阶段可独立验证。
  • 假设：CONCEPTS.md 已有 Bitable/Field Ownership/Recalc 三条目，本次需补"多维表格文件/BitableFile"新词。

Outstanding Questions

Resolve Before Planning

  • 文件层实体的具体字段集（名称/图标/描述/权限/创建人？）待 ce-plan 决定。
  • Agent 写入反馈 UI 形态（"最近写入记录高亮" vs "完整写入历史时间线"）未深入讨论，影响阶段二工作量。
  • 阶段二/三/四的具体 R 优先级与依赖排序（如 R10 看板 vs R12 公式编辑器谁先）。

Deferred to Planning

  • 文件层引入是 schema V2 升级还是独立 schema 隔离。
  • select 下拉编辑器用 vxe-table 内置 select 还是自定义组件。
  • 公式编辑器是否引入第三方库（如 formula-parser）。
  • 看板/画廊视图的组件选型（自建 vs 现成库）。
  • 文件级权限模型是复用现有 RBAC 还是新建。

Sources / Research

  • 飞书多维表格：表/视图/字段/记录四层范式；列头下拉菜单管理字段；新建表自带默认字段；多视图切换；公式列；权限；自动化；表单收集。作为本次主要参照标杆。
  • twentyhq/twenty (https://github.com/twentyhq/twenty)：开源 CRM，对象→视图→记录三栏布局范式；record 详情右侧抽屉；字段化记录模型。作为布局参照。
  • 原需求文档：docs/brainstorms/2026-06-24-bitable-module-requirements.md（5 天前，已决策"自建 + 底座心智" + v1/v2/v3 路线，本次为全量重写替代）。
  • 现有后端实现：src/agentkit/bitable/{service,repository,models,recalc_worker,db}.py + formula/{parser,functions,engine}.py + ingestion/{excel,database,api_collector}.py。
  • 现有前端实现：src/agentkit/server/frontend/src/views/BitableView.vue + src/agentkit/server/frontend/src/components/bitable/*.vue（10 个组件）+ src/agentkit/server/frontend/src/stores/bitable.ts + src/agentkit/server/frontend/src/api/bitable.ts。
  • REST API 路由：src/agentkit/server/routes/bitable.py（表/字段/记录/视图/upsert/上传/公式校验端点齐全）。
  • 已有解决方案：docs/solutions/architecture-patterns/bitable-companion-service-security-reliability-patterns.md。
  • 领域词汇：CONCEPTS.md 现有 Bitable/Field Ownership/Recalc 三条目，本次需补"多维表格文件/BitableFile"。