# F2-2 写路径报告 ## 1. 端点契约 ### POST /api/entity/{table}/save 新增(无主键)或更新(有主键)实体行,走引擎 `POJOCRUDService.save / update`。 | 项目 | 说明 | |------|------| | 请求体 | flat JSON map,键名大小写不敏感,主键字段 `{TABLE}_ID` | | 新增 | 主键为空/不传 → 引擎 `save()`,返回新生成 UUID | | 更新 | 主键非空 → 先权限检查,再引擎 `update()` | | 响应 | `{status:0, msg:"保存成功", data:{id}}` | | 错误 | 400(空体/非法表名)、403(无写权限)、500(引擎校验失败)| ### POST /api/entity/{table}/delete 软删除目标行(引擎 `delete()`,设 ISACTIVE=0;若表无 ISACTIVE 则物理删)。 | 项目 | 说明 | |------|------| | 请求体 | `{id: "uuid"}` 或 `{ids: "uuid1,uuid2"}` | | 响应 | `{status:0, msg:"删除成功", data:{deleted:N}}` | | 错误 | 400(缺 id 字段)、403(无写权限)| ### POST /api/file/upload 上传附件到本地盘(`eip4.file.root` 配置,按日期分目录),元数据写 `sys_doc`。 | 项目 | 说明 | |------|------| | 请求体 | multipart/form-data,字段名 `file` | | 响应 | `{status:0, msg:"上传成功", data:{id, name, url, size}}` | | amis 契约 | 与 amis input-file 的 `receiver` API 格式兼容 | ### GET /api/file/{id} 按 `sys_doc_id` 回取文件,带 Content-Disposition 附件头。 ## 2. 安全分层 ### 第 1 层:标识符白名单(`IdentifierWhitelist`) 表名路径变量必须在 `SYS_ENTITY` 中存在,否则 400。防 SQL 注入 / 越权操作非法表。 ### 第 2 层:写侧数据权限(`WritePrivilegeChecker`) 与读侧 `DataPrivilegeServiceImpl.getWhereClause` 语义对称: - 读侧:按 `SYS_FILTERRULE` 生成 SQL WHERE 过滤查询结果 - 写侧:loadPOJO 回读目标行,内存匹配同一套规则,不满足 → 403 支持规则类型:`CURRENTUSERID`(列值=当前用户)、`CURRENTUSERDEPARTID`、`CURRENTUSERORGID`、空条件(全放行)。复杂类型(SPECIALDEPART 等)保守放行。 ADMIN 角色跳过行级写权限检查(系统操作通道)。 ## 3. 集成实测证据 ### save → psql 落库 → delete → psql 确认删除 ``` # admin 账号 save POST /api/entity/SYS_ROLE/save Body: {"NAME":"E2E-集成测试角色-save","ENTITYTYPEID":"cc96cbb6-...","ROLETYPE":2} Response: {"status":0,"msg":"保存成功","data":{"id":"9edba318-b5fb-4ff4-b633-38b87dab5d0a"}} # psql 回读: DB count after save = 1 # delete POST /api/entity/SYS_ROLE/delete {"id":"9edba318-..."} Response: {"status":0,"msg":"删除成功","data":{"deleted":1}} # psql 回读: DB count after delete = 0(软删 isactive=0) ``` ### 数据权限写侧负例(403) ``` # ceshi 账号(CREATEBY=CURRENTUSERID 规则)删别人的 OA_DAILY 行 POST /api/entity/OA_DAILY/delete {"id":"ad2cea9e-..."} HTTP 403 Forbidden # psql 验证行仍存在: COUNT=1 ``` ### 附件上传/下载 ``` POST /api/file/upload (multipart e2e-test.txt) Response: {"status":0,"msg":"上传成功","data":{"id":"18ec0811-...","name":"e2e-test.txt","url":"/api/file/18ec0811-...","size":22}} GET /api/file/18ec0811-... Response: 200, body="hello e2e upload test" ``` ## 4. 单测覆盖 `EntityWriteControllerTest`(9 个用例,全绿,不连库): | # | 用例 | 结论 | |---|------|------| | 1 | save 新增(无主键)→ status=0,引擎 save 被调用 | pass | | 2 | save 更新(有主键)→ status=0,引擎 update 被调用,权限检查先于 update | pass | | 3 | save 非法表名 → IllegalIdentifierException | pass | | 4 | save 空请求体 → 400 | pass | | 5 | save 更新无写权限 → 403,引擎 update 不被调用 | pass | | 6 | delete 单条 → status=0, deleted=1 | pass | | 7 | delete 多条(ids 逗号分隔)→ deleted=2 | pass | | 8 | delete 无 id 字段 → 400 | pass | | 9 | delete 无写权限 → 403 | pass | 全模块 104 个单测全绿(含既有 95 个)。 ## 5. E2E 证据 `crud-write.spec.ts`(2 个用例,全绿): | # | 用例 | 结论 | |---|------|------| | 1 | amis form 提交→save端点→toast成功→psql落库→delete清理 | pass | | 2 | 数据权限写侧负例:写别人的行→403,行仍存在 | pass | 全套 30 个 E2E:28 passed,2 failed(script-replay 既有失败,与 F2-2 无关,F2-2 前已存在)。 ## 6. 已知边界 1. **`SYS_ROLE` 新增必传 `ENTITYTYPEID`**(元数据标注必填):amis form 侧已通过 hidden 字段注入默认值,API 直调须自行传入。 2. **附件服务不走旧 FTP**:直接本地 NIO + JdbcTemplate,生产迁移时需配置 `eip4.file.root` 持久化路径。 3. **写侧权限复杂规则(SPECIALDEPART/OWNNERPROJECT 等)保守放行**:与读侧 SQL 语义等价,生产可按需扩展 `WritePrivilegeChecker`。 4. **平台构建排除 platform-legacy-core**:legacy-core 含 Groovy 插件,JDK26 下不能重新编译(class file major version 70 不兼容);构建用 `-pl platform-metadata,platform-app` 跳过,本地 ~/.m2 缓存的 legacy-core jar 可用。 5. **ceshi 用户 JWT token ~17KB**(多角色导致):超过 Node.js http 默认 16KB 限制;已在 `playwright.config.ts` 中通过 `NODE_OPTIONS=--max-http-header-size=65536` 解决,后端侧 `--server.max-http-request-header-size=65536` 已在启动命令中。