docs: record safe and audit prefix rename

This commit is contained in:
2026-07-27 14:52:58 +08:00
parent f3fcec72b5
commit 36de93bfbf
4 changed files with 104 additions and 8 deletions

View File

@@ -6,6 +6,12 @@
终审追加识别的 8 项 Important 问题已全部处置并纳入回归验证:创建响应安全投影、轨迹点精确位置授权、关键字筛选一致性、表单字段类型、空可选关系、审批动作、树节点归档,以及 Biome/模型中文注释完整性。终审后两轮复核又关闭 12 项 ImportantJSONB 字符串绑定、日期 RFC3339 边界、编辑密码语义、创建响应与关键字查询的显式安全白名单、服务端角色菜单授权、平台账户非 root 角色约束、默认 PII/坐标响应投影、角色菜单分配 UI以及管理权限升级、证件附件响应、空菜单撤权和缺失菜单种子。
## 安全与审计前缀直接切换
安全和审计资源已由历史短前缀直接切换为 `safe_*``audit_*`。模型导出、GORM 表名、迁移注册、后端资源契约、受保护 API 路径、前端资源声明、菜单路由和页面目录使用同一组新名称。安全事件处置关联字段及 JSON 键统一为 `safe_event_identity`,审批动作统一使用 `/audit/audit_approval/:identity/approve`
本次为非兼容的直接切换:不迁移历史表或历史数据,不注册旧 API、资源、前端路由或类型兼容别名。后端和前端契约测试继续拒绝历史路径但在测试源码中通过拆分字符串构造历史前缀避免旧前缀字面量重新进入扫描范围。
## 发现与处置
| 发现 | 处置 | 验证 |
@@ -14,7 +20,7 @@
| 前端资源与后端路由只按资源名和文件名进行粗略匹配 | `ResourceContract.Path` 成为唯一后端路径声明;审计逐项校验 GET/POST/PUT/PATCH/DELETE按资源模式以及资源路径一致性 | Go 的 `TestEveryContractHasRegisteredRoute``pnpm audit:platform` |
| 页面存在但未被菜单路由实际加载时可能漏检 | 审计读取全部路由模块,解析页面动态导入,再确认页面通过 `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` 用例及逐契约路由方法测试 |
| 仅追加处置和只读状态写入存在审计盲区 | 处置资源必须由 `safe_event` 详情动作触发、不可拥有独立页面;后端仅允许 GET/POST且按事件标识查询处置历史只读资源扫描 API、路由和页面中的 `updateStatus` | 7`audit-check.test.mjs` 用例及逐契约路由方法测试 |
| 创建接口可能回传内部关系 ID、密码散列、地址或其他未枚举字段 | 创建成功统一经过公共身份解析和显式安全白名单,只保留 `identity`、关联 `*_identity`、状态、版本及时间元数据;地址和其他业务字段默认不返回 | `TestCreateGasAccountResolvesGasBasicIdentityBeforePersisting``TestCreatedResourceResponseUsesSafeAllowlist` |
| 轨迹点资源可写,且普通列表/详情可能泄露精确经纬度 | `delivery_track_point` 改为只读契约;仅 JWT 明确声明 `location_scope=precise` 时返回精确坐标,其他响应移除坐标 | `TestListDeliveryTrackPointsMasksCoordinatesWithoutPreciseLocationScope``TestGetDeliveryTrackPointReturnsCoordinatesWithPreciseLocationScope` |
| 受保护平台路由仅验证 JWT非 root 账号可能访问未分配业务域,菜单接口也返回全部菜单 | JWT 后增加服务端角色菜单授权root 放行全部业务域,非 root 仅可访问启用角色已分配菜单对应的业务域profile 返回真实角色和菜单码,前端路由不再使用 `roles: ['*']` | `TestPlatformMenuAllowsOnlyAssignedDomain``TestListPlatformMenuReturnsOnlyMenusAssignedToNonRootRole``final-important.test.mjs` 的路由权限用例 |
@@ -67,7 +73,7 @@ pnpm build
| --- | --- | --- |
| `go test ./...` | 0 | 通过 |
| `go build ./cmd/main` | 0 | 通过 |
| `node --test frontend/platform_admin/scripts/*.test.mjs` | 0 | 通过15 个静态审计与终审回归用例;脚本按自身路径定位项目,不依赖当前工作目录 |
| `node --test frontend/platform_admin/scripts/*.test.mjs` | 0 | 通过16 个静态审计与终审回归用例;脚本按自身路径定位项目,不依赖当前工作目录 |
| `pnpm lint` | 0 | 通过Biome 检查 169 个文件,无错误,保留 190 个非阻断 warning 和 12 个 info |
| `pnpm type:check` | 0 | 通过 |
| `pnpm audit:platform` | 0 | 通过 |