F2-8: 写体验报告(docs/P1/)

记录校验错误映射、附件控件标识、保存反馈三态、e2e 验收截图索引

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-12 00:47:48 +08:00
parent e876327c75
commit e6f108cde0

View File

@@ -0,0 +1,132 @@
# F2-8 表单写体验闭环报告
**完成日期**:2026-06-12
**状态**:验收通过(38/38 e2e 全绿)
---
## 一、校验错误映射
### 问题
`EntityWriteController.save` 抛出引擎 `ValidationException`(如"分类是必填项")时,Spring 默认返回裸 500 JSON:
```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字)"}` |
### 验证
```bash
# 校验失败(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`:
```java
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 控件:
```json
{
"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 张截图)