---
name: developing-project-management
description: Guides development of rmdc-project-management module including project lifecycle management, version control (Git-like), ACL permissions, TOTP authorization, and workflow integration. Triggered when modifying project CRUD, draft/version APIs, permission grants, or authorization features. Keywords: project mangement, project lifecycle, version snapshot, ACL, TOTP, workflow callback, SuperAdmin.
argument-hint: "<change-type> [target]" where change-type is one of: api|entity|service|migration|frontend|auth. Example: "api draft-submit" or "migration add-field"
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` 工单模块协作

## 动态上下文注入

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

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

# 查找生命周期状态相关代码
!`grep -rn "lifecycle_status\|LifecycleStatus" --include="*.go" | head -15`
```

---

## Plan（计划阶段）

### 产物清单

根据 `$ARGUMENTS` 确定变更范围：

| 变更类型 | 产物文件 | 影响模块 |
|:---|:---|:---|
| `api` | `handler/*.go`, `router.go` | rmdc-core 路由注册 |
| `entity` | `entity/*.go` | 数据库迁移、DTO 映射 |
| `service` | `service/*.go` | 业务逻辑、版本快照 |
| `migration` | `migrations/*.sql` | 数据库 Schema |
| `frontend` | `pages/*.vue`, `components/*.vue` | 前端联调 |
| `auth` | `service/auth_*.go` | TOTP 授权、Exchange-Hub 交互 |

### 决策点

1. **是否涉及生命周期状态变更?**
   - 若涉及，必须同步更新状态机转换逻辑
   - 检查 `reference/lifecycle-state-machine.md`

2. **是否修改版本快照结构?**
   - 若涉及，需评估历史版本兼容性
   - 更新 `VersionSnapshot` 结构体

3. **是否变更 ACL 权限模型?**
   - 若涉及，需同步 `rmdc-user-auth` 模块
   - 检查 `reference/acl-permission-model.md`

4. **是否影响工单模块回调?**
   - 若涉及，需更新 `ProjectLifecycleUpdater` 接口实现
   - 检查 `reference/workflow-state-mapping.md`

---

## Verify（验证阶段）

### Checklist

- [ ] **生命周期状态机完整性**: 所有状态转换有明确的触发条件和权限控制
- [ ] **版本快照一致性**: `projects` 表与 `project_versions` 表数据同步
- [ ] **乐观锁检查**: 并发修改时 `base_version == current_version` 校验存在
- [ ] **ACL 权限验证**: 接口权限注解与业务逻辑一致
- [ ] **工单回调幂等**: 状态更新操作具备幂等性
- [ ] **敏感字段加密**: 密码字段使用 AES-256 加密存储
- [ ] **审计日志**: 所有写操作记录到 `rmdc-audit-log`
- [ ] **TOTP 授权安全**: 一级密钥仅 SuperAdmin 可访问

### 验证命令

```bash
# 检查实体字段与数据库 Schema 一致性
!`grep -rn "gorm:\"" entity/project.go | head -20`

# 检查 API 路由权限注解
!`grep -rn "RequireRole\|RequirePermission" handler/*.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` 结构体定义
2. 确保 `CompareVersions` Diff 算法兼容新字段
3. 添加字段到 Diff 结果的字段名映射表
4. 测试历史版本查看功能不受影响

### 生命周期状态变更流程

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

### 授权功能变更流程

1. 检查 `project_auth_configs` 表结构
2. 更新 `AuthorizationInfo` 结构体
3. 确保 TOTP 密钥生成/验证逻辑正确
4. 测试与 Exchange-Hub 的授权指令下发

---

## Pitfalls（常见问题）

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

2. **草稿基准版本过期**: 用户 A 基于 v3 创建草稿，超管修改产生 v4，用户 A 提交时需检测冲突并提示 Rebase

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

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

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

6. **省市级联校验缺失**: 前端省市级联选择后，后端需校验省市对应关系有效性

7. **Namespace 唯一性**: 创建项目时必须校验 `namespace` 全局唯一且符合 RFC 1123 DNS 标签规范

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

---

## 模块依赖关系

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

## 关键接口

| 类别 | 路径 | 权限 |
|:---|:---|:---|
| 项目列表 | `POST /api/project/list` | Login |
| 项目详情 | `POST /api/project/detail` | View ACL |
| 创建项目 | `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 |
| 权限分配 | `POST /api/project/permission/grant` | SuperAdmin |

## 相关文档

- 生命周期状态机: `reference/lifecycle-state-machine.md`
- API 端点清单: `reference/api-endpoints.md`
- 数据库 Schema: `reference/database-schema.md`
- ACL 权限模型: `reference/acl-permission-model.md`
- 工单状态映射: `reference/workflow-state-mapping.md`