记录校验错误映射、附件控件标识、保存反馈三态、e2e 验收截图索引 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4.7 KiB
4.7 KiB
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 张截图)