platforms/docs/superpowers/plans/2026-07-27-safe-audit-model-prefix-rename.md

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: 写失败的后端资源与路由断言。

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: 写失败的前端静态断言并运行。

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: 提交测试基线。

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 类型、中文说明、迁移注册与表名。

// SafeEvent 对应 safe_event，保存安全事件统一入口。
type SafeEvent struct { /* 保持原字段和中文字段注释 */ }
func (table *SafeEvent) TableName() string { return "safe_event" }

• Step 2: 将安全处置关联列、JSON 字段、查询和测试 SQL 改为 safe_event_identity。

SafeEventIdentity string `gorm:"column:safe_event_identity;type:varchar(36);not null;index" json:"safe_event_identity"`

• Step 3: 切换后端资源契约、模型引用和路由。

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: 提交后端切换。

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、资源定义、审批动作和安全事件处置动作改为新路径。

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。

{ 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: 提交前端切换。

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: 提交验证记录。

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。