---
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: "<change-type> [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 主线 + 用户草稿分支）

## 动态上下文注入

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

```bash
# 查看项目管理模块目录结构
!`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 标签规范

### 验证命令

```bash
# 检查版本服务实现
!`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 清单、请求/响应示例 |