zeaslity/ProjectAGiPrompt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
93624efdab2cf9fc00a3a79014805dbafe43165e
ProjectAGiPrompt/1-AgentSkills/developing-project-management/SKILL.md
zeaslity 93624efdab 更新rmdc-project-management的SKILL
2026-01-22 11:58:03 +08:00

8.2 KiB
Raw Blame History

name: developing-project-management description: Guides development of rmdc-project-management module including project lifecycle management, Git-like version control with snapshot/diff, ACL permissions, TOTP authorization, and workflow integration. Triggered when modifying project CRUD, draft/version APIs, permission grants, or authorization features. Keywords: project lifecycle, version snapshot, diff algorithm, ACL, TOTP, workflow callback, SuperAdmin, optimistic lock. argument-hint: " [target]" where change-type is one of: api|entity|service|migration|frontend|auth|version. Example: "api draft-submit" or "version diff-algorithm" allowed-tools: - Read - Glob - Grep - Bash - Edit - Write

Developing Project Management Module

本 Skill 指导 rmdc-project-management 模块的开发，该模块是 RMDC 系统的核心业务模块，负责以 K8s Namespace 为粒度的项目全生命周期管理。

模块定位

  • 核心职责: 项目 CRUD、Git-like 版本控制、细粒度 ACL 权限、一级 TOTP 授权
  • 技术栈: Go + Gin + GORM + PostgreSQL (JSONB)
  • 架构: 模块化单体，通过接口注入与 rmdc-work-procedure 工单模块协作
  • 版本控制思想: 类似 Git 的分支管理（Master 主线 + 用户草稿分支）

动态上下文注入

使用前先获取当前仓库状态：

# 查看项目管理模块目录结构
!`find . -path "*/rmdc-project-management/*" -name "*.go" | head -20`

# 查找版本控制相关代码
!`grep -rn "VersionSnapshot\|CompareVersions\|DiffResult" --include="*.go" | head -15`

Plan（计划阶段）

产物清单

根据 $ARGUMENTS 确定变更范围：

变更类型 产物文件 影响模块 参考文档
api handler/*.go, router.go rmdc-core 路由注册 reference/api-endpoints.md
entity entity/*.go 数据库迁移、DTO 映射 reference/data-structures.md
service service/*.go 业务逻辑、版本快照 reference/version-control-design.md
migration migrations/*.sql 数据库 Schema reference/database-schema.md
frontend pages/*.vue, components/*.vue 前端联调 reference/frontend-design.md
auth service/auth_*.go TOTP 授权、Exchange-Hub 交互 reference/acl-permission-model.md
version service/version_*.go 版本快照、Diff 算法 reference/version-control-design.md

决策点

  1. 是否涉及生命周期状态变更? → 检查 reference/lifecycle-state-machine.md
  2. 是否修改版本快照结构? → 检查 reference/version-control-design.md 第5节
  3. 是否涉及并发修改冲突? → 检查乐观锁实现（base_version 校验）
  4. 是否变更 ACL 权限模型? → 检查 reference/acl-permission-model.md
  5. 是否影响工单模块回调? → 检查 reference/workflow-state-mapping.md

Verify（验证阶段）

Checklist

  • 生命周期状态机完整性: 所有状态转换有明确的触发条件和权限控制
  • 版本快照一致性: projects 表与 project_versions 表数据同步
  • 乐观锁检查: 并发修改时 base_version == current_version 校验存在
  • 超管直改版本生成: SuperAdmin 直接修改必须同时生成版本记录（原子事务）
  • Diff 算法正确性: 版本对比结果按模块分组，字段路径完整，中文名映射正确
  • ACL 权限验证: 接口权限注解与业务逻辑一致，授权模块仅 SuperAdmin 可见
  • 工单回调幂等: 状态更新操作具备幂等性
  • 敏感字段加密: 密码字段使用 AES-256 加密存储
  • 审计日志: 所有写操作记录到 rmdc-audit-log
  • Namespace 校验: 符合 RFC 1123 DNS 标签规范

验证命令

# 检查版本服务实现
!`grep -rn "CompareVersions\|CreateOfficialVersion\|VersionSnapshot" service/*.go`

# 检查乐观锁实现
!`grep -rn "base_version\|BaseVersion\|VersionConflict\|409" --include="*.go"`

# 检查敏感字段加密
!`grep -rn "EncryptAES\|DecryptAES\|admin_password\|ssh_pwd" --include="*.go"`

# 运行模块单元测试
go test ./internal/project/... -v -cover

Execute（执行阶段）

API 开发流程

  1. 定义请求/响应结构体 → dto/project_dto.go
  2. 实现 Service 方法 → service/project_service.go
  3. 实现 Handler 方法 → handler/project_handler.go
  4. 注册路由 → router.go (注意权限中间件)
  5. 编写单元测试 → *_test.go

版本快照变更流程

  1. 更新 VersionSnapshot 结构体定义 → reference/data-structures.md
  2. 更新字段名映射表 fieldNameMap → 确保 Diff 显示中文名
  3. 确保 CompareVersions Diff 算法兼容新字段
  4. 测试历史版本查看功能不受影响

SuperAdmin 直改流程

  1. 更新 projects 表 + 插入 project_versions 表必须在同一事务
  2. workflow_id 设为空或 DIRECT_EDIT 标识
  3. committer_id 记录 SuperAdmin ID
  4. 更新 current_version 字段

生命周期状态变更流程

  1. 更新 reference/lifecycle-state-machine.md 状态图
  2. 修改 service/lifecycle_service.go 状态转换逻辑
  3. 同步更新 ProjectLifecycleUpdater 接口实现
  4. 验证与工单模块的状态映射表一致

Pitfalls（常见问题）

  1. 超管直改未生成版本: SuperAdmin 直接修改 projects 表时，必须同时插入 project_versions 记录，否则版本链断裂，后续 Diff 失效

  2. 草稿基准版本过期: 用户 A 基于 v3 创建草稿，超管修改产生 v4，用户 A 提交时需检测冲突（draft.base_version != project.current_version）并返回 409 Conflict

  3. 工单回调重复处理: 工单模块可能重试回调，ProjectLifecycleUpdater 实现必须幂等

  4. ACL 权限遗漏授权模块: authorization_info 模块仅 SuperAdmin 可见，其他角色查询时需过滤

  5. 密码字段明文泄露: AdminPassword、SSHPwd 等字段响应时必须脱敏（返回 ********）

  6. Namespace 唯一性: 创建项目时必须校验 namespace 全局唯一且符合 RFC 1123 DNS 标签规范（小写字母开头，只含小写字母/数字/-/.）

  7. JSONB 字段空值处理: basic_info、deploy_business 等 JSONB 字段为空时，需返回空对象 {} 而非 null

  8. 版本号混淆: 草稿版本号为 0，正式版本从 1 开始递增，切勿混淆；正式版本必须保证唯一性

模块依赖关系

rmdc-project-management
├── → rmdc-user-auth (用户鉴权、ACL 权限查询)
├── ↔ rmdc-work-procedure (工单创建/状态转换 + 回调更新生命周期)
├── → rmdc-audit-log (操作审计记录)
├── → rmdc-exchange-hub (授权指令下发)
└── ← rmdc-core (路由注册、依赖注入)

关键接口速查

类别 路径 权限 说明
项目列表 POST /api/project/list Login 自动过滤 ACL
项目详情 POST /api/project/detail View ACL Master 版本
创建项目 POST /api/project/create SuperAdmin 同时创建填写工单
直接更新 POST /api/project/update SuperAdmin 必须生成新版本
保存草稿 POST /api/project/draft/save View ACL 更新草稿快照
提交审核 POST /api/project/draft/submit View ACL 检测版本冲突
版本历史 POST /api/project/version/list View ACL 仅 official 类型
版本对比 POST /api/project/version/diff View ACL 按模块分组
权限分配 POST /api/project/permission/grant SuperAdmin 模块级权限

相关文档

文档 内容
reference/lifecycle-state-machine.md 生命周期状态机、状态转换条件
reference/version-control-design.md 版本快照、Diff 算法、乐观锁、冲突检测
reference/database-schema.md DDL、索引、JSONB 结构示例
reference/data-structures.md 实体定义、枚举常量、字段校验规则
reference/acl-permission-model.md RBAC/ACL 权限模型、权限检查流程
reference/workflow-state-mapping.md 工单状态与项目生命周期映射、回调接口
reference/api-endpoints.md API 清单、请求/响应示例