F2-8: 写体验报告(docs/P1/)
记录校验错误映射、附件控件标识、保存反馈三态、e2e 验收截图索引 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
132
docs/P1/F2-8表单写体验报告.md
Normal file
132
docs/P1/F2-8表单写体验报告.md
Normal 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 张截图)
|
||||
Reference in New Issue
Block a user