diff --git a/docs/superpowers/plans/2026-07-27-safe-audit-model-prefix-rename.md b/docs/superpowers/plans/2026-07-27-safe-audit-model-prefix-rename.md new file mode 100644 index 0000000..15c0aa8 --- /dev/null +++ b/docs/superpowers/plans/2026-07-27-safe-audit-model-prefix-rename.md @@ -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`。