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

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