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>
This commit is contained in:
131
docs/P1/F2-2写路径报告.md
Normal file
131
docs/P1/F2-2写路径报告.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# 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` 已在启动命令中。
|
||||
Reference in New Issue
Block a user