diff --git a/docs/P1/F2-8表单写体验报告.md b/docs/P1/F2-8表单写体验报告.md new file mode 100644 index 0000000..b116f99 --- /dev/null +++ b/docs/P1/F2-8表单写体验报告.md @@ -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 张截图)