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

133 lines
4.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 张截图)