fix: close platform admin final audit findings
This commit is contained in:
@@ -0,0 +1,73 @@
|
||||
# Platform Admin Final Important Fixes Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 修复平台总后台终审的 8 项 Important 问题，并以回归测试、全量校验和提交记录证明修复结果。
|
||||
|
||||
**Architecture:** 后端统一在资源边界完成响应投影、关键字查询和精确位置授权，避免各页面或处理器自行绕过安全规则。前端以类型化字段定义驱动表单控件和请求载荷，并为审批与树归档提供明确交互；模型注释通过 AST 审计守住完整性。
|
||||
|
||||
**Tech Stack:** Go 1.26、Gin、GORM、Vue 3、TypeScript、Arco Design Vue、Node test runner、Biome 2.5、pnpm。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- HTTP 仅公开 `identity` 和 `<实体>_identity`，禁止公开数据库自增 ID。
|
||||
- 精确轨迹坐标必须由显式短期授权声明控制，普通列表和详情必须脱敏。
|
||||
- 可选关系为空时不进入请求体；数字、布尔、时间和 JSON 字段保持正确类型。
|
||||
- 归档为 `status=archived`，不得物理删除。
|
||||
- 所有模型字段必须有中文注释。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 后端安全边界与筛选
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/api/internal/logic/platform/task4_resources.go`
|
||||
- Modify: `backend/api/internal/logic/platform/platform.go`
|
||||
- Modify: `backend/api/internal/logic/platform/resource.go`
|
||||
- Modify: `backend/api/internal/routers/platform.go`
|
||||
- Test: `backend/api/internal/logic/platform/resource_test.go`
|
||||
- Test: `backend/api/internal/routers/platform_test.go`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Gin 查询参数、JWT `location_scope`、资源关系定义。
|
||||
- Produces: 创建响应公共投影、轨迹点脱敏处理器、通用 `keyword` 过滤。
|
||||
|
||||
- [ ] **Step 1: 写创建响应、轨迹点授权和关键字筛选失败测试。**
|
||||
- [ ] **Step 2: 运行定向 Go 测试并确认按预期失败。**
|
||||
- [ ] **Step 3: 统一创建响应投影，轨迹点改为只读授权处理器，并把安全关键字条件同时用于 count/list。**
|
||||
- [ ] **Step 4: 运行定向 Go 测试并确认通过。**
|
||||
|
||||
### Task 2: 前端类型化表单、审批和树归档
|
||||
|
||||
**Files:**
|
||||
- Modify: `frontend/platform_admin/src/api/resources.ts`
|
||||
- Create: `frontend/platform_admin/src/api/resource-form.ts`
|
||||
- Modify: `frontend/platform_admin/src/views/shared/CrudListPage.vue`
|
||||
- Modify: `frontend/platform_admin/src/views/shared/ReadOnlyListPage.vue`
|
||||
- Modify: `frontend/platform_admin/src/views/shared/TreePage.vue`
|
||||
- Test: `frontend/platform_admin/scripts/final-important.test.mjs`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `ResourceField{type, required}` 与当前表单值。
|
||||
- Produces: `buildResourcePayload(fields, form)`，以及审批 POST 和树归档交互。
|
||||
|
||||
- [ ] **Step 1: 写字段类型、空可选关系、审批动作和树归档失败测试。**
|
||||
- [ ] **Step 2: 运行 Node 测试并确认按预期失败。**
|
||||
- [ ] **Step 3: 实现类型化控件/载荷、审批详情动作和树归档确认。**
|
||||
- [ ] **Step 4: 运行 Node 测试并确认通过。**
|
||||
|
||||
### Task 3: Biome 与模型中文注释
|
||||
|
||||
**Files:**
|
||||
- Modify: `frontend/platform_admin/biome.json`
|
||||
- Modify: `backend/api/internal/models/*.go`
|
||||
- Test: `backend/api/internal/models/comments_test.go`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Biome 配置与 Go AST。
|
||||
- Produces: 不依赖缺失本地 ignore 文件的 lint 配置，以及每个导出模型字段的中文注释。
|
||||
|
||||
- [ ] **Step 1: 复现 Biome ignore-file 配置错误并写模型注释 AST 失败测试。**
|
||||
- [ ] **Step 2: 修正 Biome VCS ignore 配置，为全部模型字段补中文注释。**
|
||||
- [ ] **Step 3: 运行 `go test ./...`、Node 测试、`pnpm audit:platform`、`pnpm lint`、`pnpm type:check` 和 `pnpm build`。**
|
||||
- [ ] **Step 4: 复核差异并提交。**
|
||||
@@ -2,7 +2,9 @@
|
||||
|
||||
## 范围与结论
|
||||
|
||||
本次审计覆盖 46 个平台后台资源：34 个可写资源、11 个只读资源和 1 个仅追加的安全事件处置资源。后端资源契约现同时声明领域、资源名、HTTP 路径、页面类型和读写模式，并由运行时注册路由生成清单。前端审计据此逐项校验后端路由、前端资源声明、实际加载的页面组件和带菜单元数据的路由；任一层缺失均以 `领域/资源: missing <layer>` 失败。
|
||||
本次审计覆盖 46 个平台后台资源：33 个可写资源、12 个只读资源和 1 个仅追加的安全事件处置资源。后端资源契约现同时声明领域、资源名、HTTP 路径、页面类型和读写模式，并由运行时注册路由生成清单。前端审计据此逐项校验后端路由、前端资源声明、实际加载的页面组件和带菜单元数据的路由；任一层缺失均以 `领域/资源: missing <layer>` 失败。
|
||||
|
||||
终审追加识别的 8 项 Important 问题已全部处置并纳入回归验证：创建响应安全投影、轨迹点精确位置授权、关键字筛选一致性、表单字段类型、空可选关系、审批动作、树节点归档，以及 Biome/模型中文注释完整性。
|
||||
|
||||
## 发现与处置
|
||||
|
||||
@@ -13,6 +15,14 @@
|
||||
| 页面存在但未被菜单路由实际加载时可能漏检 | 审计读取全部路由模块，解析页面动态导入，再确认页面通过 `getResource(契约路径)` 使用对应资源且路由具有 `menu.platform.*` 元数据 | `audit-check.test.mjs` 的菜单映射用例 |
|
||||
| API 或页面可能展示、提交数据库自增 `id` / `*_id` | 对 `src/api` 与 `src/views` 全量扫描；详情页的显式过滤逻辑被识别为防护而非泄漏 | `pnpm audit:platform` |
|
||||
| 仅追加处置和只读状态写入存在审计盲区 | 处置资源必须由 `saf_event` 详情动作触发、不可拥有独立页面；后端仅允许 GET/POST，且按事件标识查询处置历史；只读资源扫描 API、路由和页面中的 `updateStatus` | 6 个 `audit-check.test.mjs` 用例及逐契约路由方法测试 |
|
||||
| 创建接口可能回传内部关系 ID、密码散列或原始个人敏感信息 | 创建成功统一经过公共身份投影和敏感字段遮罩，只保留 `identity`、关联 `*_identity` 与脱敏结果 | `TestCreateGasAccountResolvesGasBasicIdentityBeforePersisting`、`TestCreatedResourceResponseMasksSensitiveFieldsAndKeepsIdentity` |
|
||||
| 轨迹点资源可写，且普通列表/详情可能泄露精确经纬度 | `delivery_track_point` 改为只读契约；仅 JWT 明确声明 `location_scope=precise` 时返回精确坐标，其他响应清空坐标 | `TestListDeliveryTrackPointsMasksCoordinatesWithoutPreciseLocationScope`、`TestGetDeliveryTrackPointReturnsCoordinatesWithPreciseLocationScope` |
|
||||
| 通用关键字只影响列表或使用不安全字段，可能导致总数与结果不一致 | 根据模型字符串列生成受控条件，排除身份、状态、密码、坐标及审计载荷等敏感列，并将同一条件同时应用于 count/list | `TestListGasAccountAppliesKeywordToCountAndRows` |
|
||||
| 前端表单把数字、布尔、时间和 JSON 一律按字符串提交 | 资源字段显式声明类型，由 `buildResourcePayload` 统一转换请求载荷，页面按类型选择控件 | `final-important.test.mjs` 的字段类型与载荷转换用例、`pnpm type:check` |
|
||||
| 空的可选关联标识可能作为空字符串进入请求体 | 载荷边界省略空的可选 `identity` 关系，同时保留必填校验 | `final-important.test.mjs` 的空可选关系用例 |
|
||||
| 审批只读页缺少同意/驳回入口 | 资源定义声明详情动作，页面按审批身份提交动作及意见并刷新详情和列表 | `final-important.test.mjs` 的审批动作回归用例 |
|
||||
| 树页面只有新增/编辑，没有符合软删除约束的归档操作 | 增加二次确认，并调用资源归档接口写入 `status=archived`，不执行物理删除 | `final-important.test.mjs` 的树归档回归用例 |
|
||||
| Biome 依赖 worktree 中不存在的 ignore 文件，模型字段中文注释不完整 | 禁用错误的 VCS ignore 读取；新增 Go AST 测试，要求所有导出模型字段具备中文注释 | `TestEveryModelFieldHasChineseComment`、`pnpm lint` |
|
||||
|
||||
## 身份字段与保留理由
|
||||
|
||||
@@ -33,12 +43,13 @@
|
||||
cd backend/api
|
||||
go test ./...
|
||||
go build ./cmd/main
|
||||
go test ./internal/routers -run '^TestEveryContractHasRegisteredRoute$' -v
|
||||
|
||||
cd ../../frontend/platform_admin
|
||||
node --test scripts/audit-check.test.mjs
|
||||
pnpm type:check
|
||||
cd ../..
|
||||
node --test frontend/platform_admin/scripts/final-important.test.mjs
|
||||
|
||||
cd frontend/platform_admin
|
||||
pnpm lint
|
||||
pnpm type:check
|
||||
pnpm audit:platform
|
||||
pnpm build
|
||||
```
|
||||
@@ -47,9 +58,8 @@ pnpm build
|
||||
| --- | --- | --- |
|
||||
| `go test ./...` | 0 | 通过 |
|
||||
| `go build ./cmd/main` | 0 | 通过 |
|
||||
| `go test ./internal/routers -run '^TestEveryContractHasRegisteredRoute$' -v` | 0 | 通过 |
|
||||
| `node --test scripts/audit-check.test.mjs` | 0 | 通过，6 个审计用例 |
|
||||
| `node --test frontend/platform_admin/scripts/final-important.test.mjs` | 0 | 通过，4 个终审回归用例；脚本按自身路径定位项目，不依赖当前工作目录 |
|
||||
| `pnpm lint` | 0 | 通过；Biome 检查 169 个文件，无错误，保留 190 个非阻断 warning 和 12 个 info |
|
||||
| `pnpm type:check` | 0 | 通过 |
|
||||
| `pnpm audit:platform` | 0 | 通过 |
|
||||
| `pnpm build` | 0 | 通过 |
|
||||
| `pnpm lint` | 1 | 阻塞：Biome 配置在本目录要求 `.gitignore`。以 `--vcs-root=../..` 启动后发现 187 个既有全仓格式/未使用变量错误；未将无关全仓格式化混入本次审计修复。 |
|
||||
|
||||
Reference in New Issue
Block a user