---
name: developing-work-procedure
description: Guides development of rmdc-work-procedure workflow module including state machine implementation, workflow CRUD operations, status transitions, optimistic locking, WebSocket events, and Mermaid diagram generation. Triggers when modifying workflow tables, adding workflow types, changing state transitions, or implementing workflow APIs. Keywords: workflow, work-procedure, state-machine, optimistic-lock, workflow-type, transition, mermaid.
argument-hint: "<workflow-type|api-path|table-name|state-name> - specify the workflow type (user_registration|user_management|project_detail|microservice_update), API path, database table, or state to work on"
allowed-tools:
  - Read
  - Edit
  - Write
  - Glob
  - Grep
  - Bash
---

# Developing Work Procedure Module

本 Skill 指导 `rmdc-work-procedure` 工单流程模块的开发，包括状态机实现、工单 CRUD、状态转换、并发控制、事件通知与流程图生成。

## Quick Context

```bash
# 动态注入：查看模块结构
!`find . -name "*.go" -path "*/rmdc-work-procedure/*" | head -20`

# 动态注入：查看现有状态定义
!`grep -rn "status.*=" --include="*.go" ./rmdc-work-procedure/`
```

## Plan

### 产物清单
- [ ] 状态机配置/代码（状态定义、转换规则、权限矩阵）
- [ ] 数据库 Migration（workflows主表、steps表、history表、扩展表）
- [ ] API Handler + Service 实现
- [ ] WebSocket 事件推送逻辑
- [ ] Mermaid 流程图生成器
- [ ] 单元测试 + 集成测试

### 决策点
1. **工单类型**：新增还是修改现有类型？（user_registration / user_management / project_detail / microservice_update）
2. **状态扩展**：是否需要扩展状态？（如 microservice_update 的 executing/monitoring/rollbacked）
3. **并发策略**：乐观锁版本号校验是否充分？
4. **回调契约**：业务模块回调接口是否需要变更？

## Verify

### 状态机完整性
- [ ] 所有状态均有明确的入口和出口转换
- [ ] 终态（approved/rejected/revoked/closed）不可再转换
- [ ] 撤销（revoke）仅对非终态生效
- [ ] 状态转换权限矩阵与角色匹配（SuperAdmin/Creator/Assignee/System）

### 数据库一致性
- [ ] `workflows` 主表包含 `version` 字段（乐观锁）
- [ ] 扩展表 FK 正确引用 `workflows.id`
- [ ] `workflow_track_history` 记录所有状态变更
- [ ] Migration 可回滚（提供 DOWN 脚本）

### API 契约兼容
- [ ] POST 统一风格（非 RESTful GET/PUT/DELETE）
- [ ] 响应结构 `{code, message, data}` 一致
- [ ] 错误码对齐全局规范（409 版本冲突、403 权限不足、404 工单不存在）
- [ ] `version` 字段在更新请求中必传

### 事件一致性
- [ ] WebSocket 事件类型枚举完整（见 reference/websocket-events.md）
- [ ] 事件 payload 包含 workflow_id、from_status、to_status
- [ ] 通知中心模块接口调用正确

### 流程图生成
- [ ] Mermaid 源码语法正确（stateDiagram-v2）
- [ ] 当前节点高亮（classDef current）
- [ ] 前端异步加载 mermaid 库

## Execute

### 1. 状态机实现
```bash
# 检查现有状态定义
!`grep -rn "const.*Status" ./rmdc-work-procedure/`

# 创建/更新状态枚举
# 参考 reference/state-machine.md
```

### 2. 数据库变更
```bash
# 生成 migration 文件
go run cmd/migrate/main.go create add_workflow_tables

# 验证 schema
./scripts/verify-schema.sh
```

### 3. API 实现
```bash
# 查看现有 handler
!`ls -la ./rmdc-work-procedure/internal/handler/`

# 实现核心接口（参考 reference/api-contracts.md）
# - /api/workflow/create
# - /api/workflow/transition
# - /api/workflow/callback
```

### 4. 并发控制
```go
// 乐观锁更新模板（见 examples/state-transition.go）
result := db.Model(&Workflow{}).
    Where("id = ? AND version = ?", id, version).
    Updates(map[string]interface{}{
        "status":  newStatus,
        "version": gorm.Expr("version + 1"),
    })
if result.RowsAffected == 0 {
    return ErrVersionConflict // 409
}
```

### 5. 测试验证
```bash
# 运行状态机测试
go test ./rmdc-work-procedure/... -run TestStateMachine -v

# 验证 API 契约
./scripts/verify-api-contracts.sh
```

## Pitfalls

1. **版本号遗漏**：更新工单时忘记传递 `version` 字段，导致乐观锁失效；客户端需缓存并回传 version
2. **终态误转换**：对 approved/rejected/revoked/closed 状态尝试非法转换，需在服务层硬校验
3. **扩展表不同步**：创建工单时忘记同步写入对应 `*_ext` 扩展表，导致业务数据丢失
4. **事件推送遗漏**：状态变更后忘记调用通知中心，处理人无法收到实时通知
5. **撤销硬删除**：user_registration 类型撤销需硬删除用户，其他类型仅标记状态
6. **回调幂等**：业务模块回调 `/api/workflow/callback` 需做幂等处理，避免重复状态变更
7. **草稿状态混淆**：project_detail 的 `draft_saved` 是扩展状态，不属于基础状态机
8. **Mermaid 安全**：前端初始化 mermaid 需设置 `securityLevel: 'strict'`，避免 XSS

## Related References

- [状态机定义](reference/state-machine.md)
- [数据库 Schema](reference/database-schema.md)
- [API 契约](reference/api-contracts.md)
- [工单类型详情](reference/workflow-types.md)
- [WebSocket 事件](reference/websocket-events.md)
