docs: plan safe and audit prefix rename
This commit is contained in:
@@ -0,0 +1,172 @@
|
||||
# Safe 与 Audit 模型前缀重命名 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:** 将安全与审计领域的 `saf_`、`aud_` 命名统一切换为 `safe_`、`audit_`，并保持模型、API、前端与资源契约一致。
|
||||
|
||||
**Architecture:** 模型类型和表名直接切换到新前缀；后端资源契约与路由以新资源名注册；前端资源、页面目录与路由随之切换。此为非兼容重命名：不迁移旧表，也不保留旧 API 别名。
|
||||
|
||||
**Tech Stack:** Go、Gin、GORM、Vue 3、TypeScript、Node test、pnpm。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- 不迁移 `saf_*`、`aud_*` 历史表或数据。
|
||||
- 不保留旧前缀 API、资源、前端路由或类型别名。
|
||||
- `backend/api/internal/models` 的导出字段保留中文注释。
|
||||
- 每项实现必须遵循 RED-GREEN：先写并运行失败测试，再写最小实现。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 资源命名契约测试
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/api/internal/logic/platform/resource_test.go`
|
||||
- Modify: `backend/api/internal/routers/platform_test.go`
|
||||
- Modify: `frontend/platform_admin/scripts/audit-check.test.mjs`
|
||||
|
||||
**Interfaces:** 产出资源 `safe_rule`、`safe_event`、`safe_inspection`、`safe_event_disposal`、`audit_operation_log`、`audit_export_log`、`audit_approval`，并注册 `/safety/safe_*`、`/audit/audit_*` 路径。
|
||||
|
||||
- [ ] **Step 1: 写失败的后端资源与路由断言。**
|
||||
|
||||
```go
|
||||
assertContract(t, ExpectedResources(), "safety", "safe_event", Writable, "list")
|
||||
assertRouteMethods(t, routes, "/heqi/platform/v1/audit/audit_approval/:identity/approve", http.MethodPost)
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行并确认失败。**
|
||||
|
||||
Run: `go test ./internal/logic/platform ./internal/routers -run 'Test.*(Safe|Audit)' -v`
|
||||
|
||||
Expected: FAIL，旧前缀尚未替换。
|
||||
|
||||
- [ ] **Step 3: 写失败的前端静态断言并运行。**
|
||||
|
||||
```js
|
||||
assert.match(resourcesSource, /define\('safe_event', '\/safety\/safe_event'/);
|
||||
assert.match(resourcesSource, /define\('audit_approval', '\/audit\/audit_approval'/);
|
||||
```
|
||||
|
||||
Run: `node --test scripts/audit-check.test.mjs`
|
||||
|
||||
Expected: FAIL。
|
||||
|
||||
- [ ] **Step 4: 提交测试基线。**
|
||||
|
||||
```powershell
|
||||
git add backend/api/internal/logic/platform/resource_test.go backend/api/internal/routers/platform_test.go frontend/platform_admin/scripts/audit-check.test.mjs
|
||||
git commit -m "test: define safe and audit resource rename contract"
|
||||
```
|
||||
|
||||
### Task 2: 重命名模型与后端资源
|
||||
|
||||
**Files:**
|
||||
- Rename: `backend/api/internal/models/saf_{rule,event,event_disposal,inspection}.go` → 对应 `safe_*.go`
|
||||
- Rename: `backend/api/internal/models/aud_{approval,export_log,operation_log}.go` → 对应 `audit_*.go`
|
||||
- Modify: `backend/api/internal/models/query.go`
|
||||
- Modify: `backend/api/internal/logic/platform/{resource,audit,task4_resources,health_test,resource_test,audit_test}.go`
|
||||
- Modify: `backend/api/internal/routers/{platform,platform_test}.go`
|
||||
|
||||
**Interfaces:** 产出 `models.SafeRule`、`SafeEvent`、`SafeEventDisposal`、`SafeInspection`、`AuditApproval`、`AuditExportLog`、`AuditOperationLog`；GORM 表名为 `safe_*`、`audit_*`。
|
||||
|
||||
- [ ] **Step 1: 重命名七个模型的文件、Go 类型、中文说明、迁移注册与表名。**
|
||||
|
||||
```go
|
||||
// SafeEvent 对应 safe_event，保存安全事件统一入口。
|
||||
type SafeEvent struct { /* 保持原字段和中文字段注释 */ }
|
||||
func (table *SafeEvent) TableName() string { return "safe_event" }
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 将安全处置关联列、JSON 字段、查询和测试 SQL 改为 `safe_event_identity`。**
|
||||
|
||||
```go
|
||||
SafeEventIdentity string `gorm:"column:safe_event_identity;type:varchar(36);not null;index" json:"safe_event_identity"`
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 切换后端资源契约、模型引用和路由。**
|
||||
|
||||
```go
|
||||
registerRestrictedWritableResource(group, "/safety/safe_event", &models.SafeEvent{}, allowed)
|
||||
registerReadOnlyResource(group, "/audit/audit_approval", &models.AuditApproval{})
|
||||
group.POST("/audit/audit_approval/:identity/approve", platform.ApproveAudit)
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 运行 Task 1 后端测试，确认 PASS。**
|
||||
|
||||
- [ ] **Step 5: 提交后端切换。**
|
||||
|
||||
```powershell
|
||||
git add backend/api/internal/models backend/api/internal/logic/platform backend/api/internal/routers
|
||||
git commit -m "refactor: rename safe and audit backend resources"
|
||||
```
|
||||
|
||||
### Task 3: 切换前端资源、页面和路由
|
||||
|
||||
**Files:**
|
||||
- Modify: `frontend/platform_admin/src/api/{platform,resources}.ts`
|
||||
- Modify: `frontend/platform_admin/src/router/routes/modules/{safety,audit}.ts`
|
||||
- Rename: `frontend/platform_admin/src/views/safety/saf_*` → `safe_*`
|
||||
- Rename: `frontend/platform_admin/src/views/audit/aud_*` → `audit_*`
|
||||
- Modify: `frontend/platform_admin/scripts/{audit-check,audit-check.test,final-important.test}.mjs`
|
||||
|
||||
**Interfaces:** 消费 Task 2 新 API；产出 `getResource('/safety/safe_event')`、`getResource('/audit/audit_approval')`。
|
||||
|
||||
- [ ] **Step 1: 将 labels、资源定义、审批动作和安全事件处置动作改为新路径。**
|
||||
|
||||
```ts
|
||||
define('safe_event', '/safety/safe_event', 'writable', 'list', fields)
|
||||
action('safe_event_disposal', '/safety/safe_event/:identity/disposals', fields)
|
||||
define('audit_approval', '/audit/audit_approval', 'readonly', 'list', fields)
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 重命名页面目录与路由动态导入，并更新菜单 locale key。**
|
||||
|
||||
```ts
|
||||
{ path: 'safe-event', name: 'safety-safe-event', component: () => import('@/views/safety/safe_event/ListPage.vue') }
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 更新静态审计和前端回归，确认 Task 1 前端断言转绿。**
|
||||
|
||||
Run: `node --test scripts/audit-check.test.mjs scripts/final-important.test.mjs; pnpm audit:platform; pnpm type:check`
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
- [ ] **Step 4: 提交前端切换。**
|
||||
|
||||
```powershell
|
||||
git add frontend/platform_admin/src frontend/platform_admin/scripts
|
||||
git commit -m "refactor: rename safe and audit frontend resources"
|
||||
```
|
||||
|
||||
### Task 4: 清理与全量验证
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/平台总后台审计报告-2026-07-27.md`
|
||||
|
||||
- [ ] **Step 1: 搜索旧前缀，确认生产代码和测试无命中。**
|
||||
|
||||
Run: `rg -n "\\b(Saf|Aud)[A-Za-z]|saf_|aud_" backend/api frontend/platform_admin/src frontend/platform_admin/scripts`
|
||||
|
||||
Expected: 退出码 1。
|
||||
|
||||
- [ ] **Step 2: 更新报告，记录直接切换且不迁移旧数据。**
|
||||
|
||||
- [ ] **Step 3: 运行完整验证。**
|
||||
|
||||
Run（`backend/api`）: `go test ./...; go build ./cmd/main`
|
||||
|
||||
Run（`frontend/platform_admin`）: `node --test scripts/*.test.mjs; pnpm lint; pnpm type:check; pnpm audit:platform; pnpm build`
|
||||
|
||||
Expected: 测试、构建、类型检查与资源审计 PASS；lint 无 error。
|
||||
|
||||
- [ ] **Step 4: 提交验证记录。**
|
||||
|
||||
```powershell
|
||||
git add docs/平台总后台审计报告-2026-07-27.md
|
||||
git commit -m "docs: record safe and audit prefix rename"
|
||||
```
|
||||
|
||||
## Plan Self-Review
|
||||
|
||||
- 规格覆盖：Task 2 覆盖模型、类型、表名、后端路由与资源；Task 3 覆盖前端资源、页面与路由；Task 4 验证旧命名不残留。
|
||||
- 数据策略：未定义 SQL 重命名或兼容别名，符合不迁移历史数据的约束。
|
||||
- 命名一致：安全处置关联字段与资源路径使用 `safe_event`；审批资源与动作使用 `audit_approval`。
|
||||
Reference in New Issue
Block a user