fix(plugin-grid): 「下载模板」列出全部字段（含系统/只读列），改调后端模板接口

[baozhoutao]

问题

导入页面的「下载模板」按钮,生成的模板把对象所有字段都列了出来,包括用户填了也写不进去的系统字段和只读字段。

以一个业务对象(项目)为例,模板前 7 列全是 registry 注入的系统字段:组织标识、创建时间、创建人、更新时间、更新人、所有者、所属业务单元。因为这些字段是 registry 给每个对象注入的,所以所有对象的模板都这样,不是个别对象配错。

根因

buildImportTemplateCsv(fields)(packages/plugin-grid/src/ImportWizard.tsx)无条件把传入的 fields 全部列成表头,而这份 fields 来自 importTargetFields(objectDef.name, objectDef.fields, perms)(packages/app-shell/src/views/ObjectView.tsx)——它的用途是映射步骤的候选目标列表,故意放得很宽:

• writable 字段(不论常用与否)
• 外加 matchOnly 的只读 / autonumber 字段(仅供 upsert 匹配,不能写入)

matchOnly 这个标记在模板生成时完全没被用上。此外 ImportTargetField 根本没把 schema 上的 system / hidden 带出来,所以即便想过滤也没有依据。

比「列太多」更严重的是:这些只读列在导入时会被服务端 stripReadonlyFields 静默剥掉。用户照模板填了「创建人」,导入成功、无报错、数据没进去。模板在教用户填注定被丢弃的列。

方案:删掉前端生成,改调后端模板接口

模板不该有两套实现。framework 侧正在为导出接口新增模板模式(objectstack-ai/objectstack#18386):

GET /data/:object/export?template=true

它返回 0 行 + 只含「可填列」的 xlsx,并为 select / boolean 列挂 Excel 数据验证下拉、附一个「填写说明」sheet 说明值域与分隔符 —— 这些是 CSV 表达不了的。列规则、值域口径统一在服务端定义一次。

本仓库要做的:

1. 「下载模板」按钮改为请求上述接口并触发下载
2. 删除 buildImportTemplateCsv、exampleForField、firstOptionValue、downloadTextFile(如无其他调用方)及 importTemplate.test.ts
3. importTargetFields 保持不变 —— 它作为映射步骤的候选列表是正确的,matchOnly 字段必须继续留在映射里供 upsert 匹配(见该文件注释 Add full-featured form component similar to Airtable #20:「记录编号往往是文件里唯一的自然键」)

净效果是减代码,约 -70 行加一个测试文件。

不需要新增依赖

前端不再生成文件,只触发下载,因此不需要 SheetJS / exceljs 之类的前端 xlsx 库。

验收

1. 任一对象点「下载模板」,得到的 xlsx 不含系统字段 / 只读字段 / 公式字段 / 自动编号列
2. 映射步骤的目标字段候选不受影响,matchOnly 字段仍可选中用于 upsert 匹配
3. 下载的模板填入数据后原样上传,导入成功且无 invalid_option / invalid_boolean
4. 前端无新增依赖

依赖

必须等 objectstack-ai/objectstack#18386 落地并发版后才能开工。

[objectstack-fleet]

Status check from the triage seat, on the maintainer's instruction. 2026-09-28T09:35Z.

Provenance. Executed on the maintainer's instruction. In the triage seat's chat (session session_01AavokzJ5DndAwitDXvKy4U, 2026-09-28), the seat's owned-card review listed this card under item 5 (a reminder on each card held by baozhoutao), and the maintainer replied, verbatim: 「v18 还没开始。其他同意，长期项目: 具体列出来按照总监决策的格式和我讨论」.

@baozhoutao: this card is assigned to you. It has no labels, and has not moved since 2026-09-16. It depends on objectstack-ai/objectstack#18386 landing and being released, and that card has not moved either.

• Still yours: a line on the next step keeps it.
• Not being worked: clear the assignee, and triage grades and routes it.

[objectstack-fleet]

Takeover: this card now sits with the domain:spec @ objectui seat, blocked on its framework half. Session session_012UwY3ahMixEFkfTUxMVkYm, seat domain:spec#1, 2026-09-29T15:30Z. ⛔ Not a dispatch.

Blocked-by: objectstack-ai/objectstack#18386

Provenance. The maintainer, in this seat's chat, 2026-09-29, verbatim: 「objectui#9600(baozhoutao),objectui#7650(os-zhuang) 这两个任务如果没有人在处理，你也可以接手」.

Nobody is working it. Read at this stamp:

• No PR or branch carries this card's number.
• The card had no labels, and has not moved since 2026-09-16. The triage status check 5867307137 (2026-09-28) has no answer.

So in this act (read back): baozhoutao is unassigned, huangyiirene is assigned, and the card gets pm:blocked and domain:ui (the fix lands in packages/plugin-grid and packages/app-shell). ⛔ No priority is set: grading is triage's.

The gate.

• The card body says, verbatim: 「必须等 feat(rest): 导出接口新增 ?template=true —— 输出只含「可填列」的 xlsx 导入模板 objectstack#18386 落地并发版后才能开工。」
• objectstack#18386 was claimed at 2026-09-29T15:27Z by the objectstack domain:spec seat 5 (os-justin, claim 5893328151), also on the maintainer's instruction.
• When it closes, the unlock sweep also checks that a published @objectstack release carries GET /data/:object/export?template=true before this card returns to the queue. That is the consumer-installable rule, so the merge alone does not reopen it.

When unblocked, this seat claims it. The scope is the card's own: the 「下载模板」 button calls the template endpoint; buildImportTemplateCsv and its helpers are deleted if nothing else calls them; importTargetFields stays unchanged.

[objectstack-fleet]

Pointer from objectstack: the framework half of this card has landed · 2026-09-30T11:00Z

domain:spec seat 5 of objectstack (session_01Sfe5YjBLwB9J3y8fvm2xq1). ⛔ Not a claim; no state change here.

• Landed: feat(rest): 导出接口新增 ?template=true —— 输出只含「可填列」的 xlsx 导入模板 objectstack#18386 landed through PR feat(rest): GET /data/:object/export?template=true answers an xlsx import template (#18386) objectstack#20683 as e5c7d07ed4. GET /api/v1/data/:object/export?template=true answers the xlsx import template: the columns an import stores, required columns with no default marked *, dropdowns for select / radio / boolean, and an instructions sheet.
• The response header X-Export-Template-Projection says how the columns were narrowed (writable, readable or none).
• Before this card's button can call the endpoint, a framework release must carry e5c7d07ed4. The objectstack card stays open only for its acceptance 6, which is a hand check in four spreadsheet apps.

---

Generated by Claude Code

[objectstack-fleet]

Pointer from objectstack: two things the 「下载模板」 wiring must honour, from the #18386 acceptance-6 machine verification · 2026-09-30T16:13Z

domain:spec seat 5 of objectstack (session_01Sfe5YjBLwB9J3y8fvm2xq1). ⛔ Not a claim; no state change here. Readings: objectstack-ai/objectstack#18386 comment 5914688255.

• The import must carry the same locale as the download. A template writes option labels in the request's locale, and the import door accepts a translated label only under the import request's locale. Measured: a zh-CN template imported under an en request answers invalid_option ("Status: "待办" is not a known option"). The same file imported under zh-CN is accepted. Boolean 是/否 is locale-independent. The import wizard must send the locale the template was downloaded in, or the user's current locale if the two cannot differ.
• The gate is being decided. Today the template needs allowExport on the object (the export gates run first), so an importer without export permission gets 403 EXPORT_NOT_PERMITTED. The import template (GET /data/:object/export?template=true) sits behind the EXPORT gate (allowExport): a caller who may import but not export cannot download it — gate it by the import door instead? (from #18386 acceptance-6 verification) objectstack#20896 asks the maintainer whether the template should follow the import door instead. The seat recommends A (the import door). The button's 403 handling depends on that answer.

---

Generated by Claude Code