---
name: developing-project-management 项目管理模块开发指南
description: "Guides development of rmdc-project-management 模块：项目全生命周期管理（Project Lifecycle）、类 Git 版本管理（snapshot/diff，支持草稿/发布/回滚）、ACL 权限控制、TOTP 二次授权、与工单(work-procedure)的联动回调，以及 Vue3 + Vuetify 前端页面/组件开发。Triggered when you modify 项目 CRUD、草稿/版本相关 API（draft/version）、权限授予与授权能力（ACL/TOTP/SuperAdmin）、工作流回调与状态同步、数据库迁移，或前端 ProjectDetail 等页面与组件。Keywords: 项目生命周期, 版本快照, diff 算法, ACL, TOTP, workflow callback, SuperAdmin, optimistic lock/乐观锁, Vue3, Vuetify, ProjectDetail."
argument-hint: "<change-type> [target] — change-type 可选: api|entity|service|migration|frontend|auth|version|component. Examples: \"api draft-submit\" / \"frontend ProjectDetail\" / \"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)
- **前端技术栈**: Vue3 + TypeScript + Vuetify3
- **架构**: 模块化单体，通过接口注入与 `rmdc-work-procedure` 工单模块协作
- **版本控制思想**: 类似 Git 的分支管理（Master 主线 + 用户草稿分支）

## 动态上下文注入

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

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

# 查看前端组件目录结构
!`find . -path "*/admin/components/*" -name "*.vue" | head -20`

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

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

---

## Plan（计划阶段）

### 产物清单

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

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

### 决策点

1. **是否涉及生命周期状态变更?** → 检查 `reference/02-lifecycle-state-machine/lifecycle-states.md`
2. **是否修改版本快照结构?** → 检查 `reference/04-version-control/version-design.md`
3. **是否涉及并发修改冲突?** → 检查乐观锁实现（base_version 校验）
4. **是否变更 ACL 权限模型?** → 检查 `reference/03-permission-model/acl-permission.md`
5. **是否影响工单模块回调?** → 检查 `reference/02-lifecycle-state-machine/workflow-state-mapping.md`
6. **是否涉及前端页面修改?** → 检查 `reference/07-frontend-design/page-architecture.md`
7. **是否涉及用户侧/管理侧差异?** → 检查 `reference/07-frontend-design/user-admin-difference.md`

---

## Verify（验证阶段）

### 后端 Checklist

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

### 前端 Checklist

- [ ] **状态分离**: 查看/编辑模式正确切换，`isEditMode` 状态管理正确
- [ ] **脏数据检测**: `hasChanges` computed 正确计算，退出时有确认对话框
- [ ] **角色差异化**: SuperAdmin 与普通用户看到的 Tab 和操作按钮符合设计
- [ ] **生命周期展示**: 状态标签颜色、图标、Alert Banner 符合规范
- [ ] **工单关联**: 多工单场景正确处理，跳转链接正确
- [ ] **组件复用**: 共用组件正确抽离，Props 和 Emits 设计合理
- [ ] **响应式布局**: 移动端适配正确，断点设置符合 Vuetify 规范
- [ ] **TypeScript 类型**: 类型定义完整，无 any 类型

### 验证命令

```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"`

# 检查前端生命周期状态
!`grep -rn "LIFECYCLE_STATUS\|getLifecycleStatusColor" --include="*.vue" --include="*.ts"`

# 检查前端组件引用
!`grep -rn "BasicInfoReadonly\|SaveConfirmDialog" --include="*.vue"`

# 运行模块单元测试
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/05-database-schema/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. **只读组件** → `*Readonly.vue`，使用 `v-row/v-col` 布局
2. **表单组件** → `*Form.vue`，使用 Vuetify 表单组件
3. **组件导出** → 更新 `components/index.ts`
4. **页面集成** → 在 `ProjectDetail.vue` 或 `UserProjectDetail.vue` 中引用
5. **类型定义** → 更新 `types/*.ts`

### 前端状态管理流程

1. **进入编辑模式**: 深拷贝 `masterData` → `editForm`
2. **修改检测**: 使用 `hasChanges` computed
3. **保存前确认**: 使用 `SaveConfirmDialog` 展示 Diff
4. **退出保护**: 有未保存修改时弹出确认对话框

---

## Pitfalls（常见问题）

### 后端

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

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

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

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

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

### 前端

6. **编辑模式状态未同步**: 切换 Tab 时 `isEditMode` 状态可能丢失，需使用 `v-window` 而非条件渲染

7. **Diff 计算不完整**: 对比时遗漏嵌套字段，需使用递归 JSON Diff

8. **工单按钮显示错误**: 多工单场景下 `workflow_id` 可能是数组，需正确处理

---

## 模块依赖关系

```
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/draft/diff` | View ACL | 草稿与主线 Diff |
| 版本历史 | `POST /api/project/version/list` | View ACL | 仅 official 类型 |
| 版本对比 | `POST /api/project/version/diff` | View ACL | 按模块分组 |
| 权限分配 | `POST /api/project/permission/grant` | SuperAdmin | 模块级权限 |

## 前端页面速查

| 页面 | 路径 | 角色 | 说明 |
|:---|:---|:---|:---|
| 管理员项目详情 | `pages/admin/ProjectDetail.vue` | SuperAdmin | 全功能，含授权/版本历史 |
| 用户项目详情 | `pages/user/UserProjectDetail.vue` | User | 草稿编辑，提交审核 |

## 相关文档（章节分层）

| 章节目录 | 内容 |
|:---|:---|
| `reference/01-architecture-overview/` | 模块依赖关系 |
| `reference/02-lifecycle-state-machine/` | 生命周期状态机、工单状态映射 |
| `reference/03-permission-model/` | ACL 权限模型、权限检查流程 |
| `reference/04-version-control/` | 版本快照、Diff 算法、乐观锁 |
| `reference/05-database-schema/` | DDL、索引、数据结构定义 |
| `reference/06-api-design/` | API 清单、业务流程 |
| `reference/07-frontend-design/` | 前端页面架构、组件规范、交互时序 |