Files
eip4-platform/docs/P1/F2-8表单写体验报告.md
zhengwr e6f108cde0 F2-8: 写体验报告(docs/P1/)
记录校验错误映射、附件控件标识、保存反馈三态、e2e 验收截图索引

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-12 00:47:48 +08:00

4.7 KiB
Raw Blame History

F2-8 表单写体验闭环报告

完成日期:2026-06-12
状态:验收通过(38/38 e2e 全绿)


一、校验错误映射

问题

EntityWriteController.save 抛出引擎 ValidationException(如"分类是必填项")时,Spring 默认返回裸 500 JSON:

{"timestamp":"...","status":500,"error":"Internal Server Error","path":"..."}

前端 amis form 无法解析,显示空白或无提示。

解决方案

新增 WriteExceptionHandler.java(@RestControllerAdvice(assignableTypes={EntityWriteController,FileController})):

异常类型 HTTP 状态 amis 响应体
ValidationException 422 {status:422, msg:"分类是必填项"}
PrivilegeException 403 {status:403, msg:"无操作权限"}
其他 RuntimeException 500 {status:1, msg:"...(截断200字)"}

验证

# 校验失败(NAME 空白,引擎必填规则触发)
POST /api/entity/SYS_ROLE/save {"NAME":" "}
→ HTTP 422: {"status":422,"msg":"分类是必填项"}   ✓ 非裸 500

# 正常保存
POST /api/entity/SYS_ROLE/save {"NAME":"测试","ENTITYTYPEID":"c762a88c...","ROLETYPE":1}
→ HTTP 200: {"status":0,"msg":"保存成功","data":{"id":"..."}}  ✓

附件列标识结论

  • 标识方式:SYS_ENTITYATTRIBUTE.referenceid = 'BLOB'(292 个字段)
  • XML 中 uitype:MultiFileUploadField(多附件)/ FileUploadField(单附件)
  • 典型字段名:DOCUMENT

二、附件控件

转换器变更

UiTypeMapper.java 新增 case MultiFileUploadField / FileUploadField:

case "MultiFileUploadField", "FileUploadField" -> {
    item.put("type", "input-file");
    item.put("receiver", "/api/file/upload");
    item.put("downloadUrl", "/api/file/${id}");
    if (multi) item.put("multiple", true);
}

生成 amis 控件:

{
  "name": "DOCUMENT",
  "label": "附件",
  "type": "input-file",
  "receiver": "/api/file/upload",
  "downloadUrl": "/api/file/${id}",
  "multiple": true
}

已有后端

FileController(POST /api/file/upload,GET /api/file/{id})已完整实现,符合 amis input-file 契约(返回 {status:0, data:{id,name,url,size}})。

说明

  • 现有转换产物(71 个 form)在本次改动前已落库,DOCUMENT 字段仍为 input-text
  • 重批命令(见任务说明)执行后即可批量更新
  • 实证:单元测试 form_附件字段MultiFileUploadField转inputFile 验证转换正确(28/28 pass)

三、保存反馈

amis form 收到 status:0 时自动显示成功 toast,status≠0 时显示 msg 文案。行为由 amis SDK 默认处理,无需额外配置。

  • 成功:status:0, msg:"保存成功" → amis toast「保存成功」,3s 消失
  • 校验失败:status:422, msg:"分类是必填项" → amis form 顶部红色 alert
  • 403 数据权限:status:403, msg:"无操作权限" → amis form 顶部红色 alert(非裸 Spring JSON)
  • 脏数据离开:amis form 自带 confirmText 机制,schema 层面无需额外配置

截图存于 e2e/artifacts/f2-8/:

  • f2-8-1-form-initial.png — 表单初始状态
  • f2-8-1-form-success-toast.png — 成功提交后
  • f2-8-2-validation-error.png — amis 客户端必填校验
  • f2-8-2-server-validation-error.png — 引擎服务端校验(422)

四、e2e 测试

新增 e2e/form-write.spec.ts,三个测试用例(真实转换产物 SYS_ROLE 实体):

测试 ID 场景 结论
E2E-F2-8-1 填必填→提交→toast→psql 落库→清理 PASS
E2E-F2-8-2 必填留空→amis 行内错误 + 服务端 422 非裸500 PASS
E2E-F2-8-3 低权限写受限行→友好 msg(Node 侧 API 验证) PASS

终验数:38/38(原基线 35 + 新增 3)


五、顺手修(P1-5)

项 文件 改动
BACKEND_NODE 未用变量 e2e/f2-16-column-render.spec.ts:17 删除
schema-samples 截图竞态 e2e/schema-samples.spec.ts 截图前等 .cxd-Page-body 可见
f2-16 截图竞态 e2e/f2-16-column-render.spec.ts 截图前等表格/Page-body 可见

六、变更文件清单

eip4-platform:

  • platform-metadata/src/main/java/.../web/WriteExceptionHandler.java(新增)
  • platform-converter/src/main/java/.../converter/UiTypeMapper.java(附件字段映射)
  • platform-converter/src/test/.../converter/TemplateToAmisConverterTest.java(附件测试)

eip4-web:

  • e2e/form-write.spec.ts(新增,F2-8 三态 e2e)
  • e2e/f2-16-column-render.spec.ts(删 BACKEND_NODE + 截图竞态修复)
  • e2e/schema-samples.spec.ts(截图竞态修复)
  • e2e/artifacts/f2-8/(4 张截图)