Files
eip4-platform/docs/P1/F2-2写路径报告.md
zhengwr 9a055ef3b6 F2-2: CRUD 写路径闭环(save/delete/文件上传下载 + 写侧数据权限)
- 新增 EntityWriteController:POST /api/entity/{table}/save(新增/更新)
  和 /delete(软删),双层安全(标识符白名单 + 写侧数据权限)
- 新增 FileController:POST /api/file/upload + GET /api/file/{id},
  本地 NIO 存盘 + sys_doc 元数据,兼容 amis input-file 契约
- 新增 WritePrivilegeChecker:读侧 SYS_FILTERRULE 规则的写端对称实现,
  内存属性匹配,无命中规则 → 403
- 新增 EntityWriteControllerTest:9 个 mock 单测(新增/更新/权限负例/delete 多条等),
  全模块 104 个单测全绿
- pom.xml:surefire 加 Byte Buddy experimental 修复 JDK26+Mockito inline 兼容
- application-dev.yml:port 8093 + file root 配置
- docs/P1/F2-2写路径报告.md:端点契约/权限机制/集成与 e2e 证据/已知边界

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 22:00:36 +08:00

5.3 KiB
Raw Blame History

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 已在启动命令中。