--- date: 2026-06-29 topic: 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](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"。