---
name: developing-user-auth

description: >
  指导开发 rmdc-user-auth 用户认证与权限模块（v2.0），覆盖：
  JWT认证（HS256、4h有效期、claims注入）、RSA-OAEP加密登录（2048密钥、30天轮换）、
  密码安全（bcrypt存储、3个月过期、首次登录强制改密 must_change_password）、
  账户有效期（account_expires_at、非SuperAdmin必须设置有效期）、
  RBAC权限模型（superadmin/admin/normal/third四级角色、谁注册谁管理原则、registered_by_id）、
  统一权限架构（PermissionModule枚举、jenkins_acls层级权限、project_acls模块级权限、user_permission_caches L2缓存）、
  用户生命周期（disabled→active→locked状态机、工单审批激活）、
  用户注册/管理工单集成（接口注入机制、UserStatusUpdater/WorkflowCreator回调、工单由用户接口内部自动创建）。
  触发场景：修改auth handlers、permission services、user CRUD、workflow callbacks、password policies、JWT/RSA实现。
  Keywords: JWT / RSA-OAEP / bcrypt / RBAC / PermissionModule / jenkins_acls / project_acls / account_expires_at / must_change_password / workflow integration.

allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
  - Edit
  - Write

argument-hint: "$ARGUMENTS: <变更类型> [目标文件] — 变更类型: auth|permission|user-crud|workflow|password-policy|jwt|rsa|account-validity"

---

# developing-user-auth（用户认证模块）

## 概述
本 Skill 指导 `rmdc-user-auth` 模块的开发，覆盖认证、权限、用户生命周期、工单集成等核心功能。基于 DDS v2.0 设计规范。

## 动态上下文注入

### 查看模块结构
!`find . -type f -name "*.go" -path "*user-auth*" | head -30`

### 查找权限相关代码
!`grep -rn "PermissionModule\|CheckPermission\|jenkins_acls\|project_acls" --include="*.go" | head -20`

### 查看用户表结构
!`grep -A 60 "type User struct" internal/models/*.go`

### 查看工单回调接口
!`grep -rn "UserStatusUpdater\|WorkflowCreator\|ActivateUser" --include="*.go" | head -15`

---

## Plan（规划阶段）

### 产物清单
根据 `$ARGUMENTS` 确定变更范围：

| 变更类型 | 涉及文件 | 下游影响 |
|:---|:---|:---|
| auth | `auth_handler.go`, `auth_service.go` | 前端登录流程、JWT claims、密码过期检查 |
| permission | `permission_handler.go`, `*_permission_service.go`, `*_acl_dao.go` | Jenkins DAC、Project权限、其他模块权限检查 |
| user-crud | `user_handler.go`, `user_service.go`, `user_dao.go` | 工单模块回调、审计日志、账户有效期 |
| workflow | `user_workflow_handler.go`, `*_workflow_service.go` | rmdc-work-procedure 回调 |
| password-policy | `auth_service.go`, `rsa_service.go` | password_expires_at、must_change_password |
| jwt | `auth_middleware.go`, `jwt_utils.go` | 所有需鉴权接口、account_expires_at 检查 |
| rsa | `rsa_service.go`, `rsa_keypair_dao.go` | 前端公钥获取、密钥轮换 |
| account-validity | `user_model.go`, `auth_service.go` | 登录检查、有效期设置规则 |

### 决策点
- [ ] 是否涉及 JWT claims 字段变更？→ See: [reference/03-authentication/jwt-claims.md](reference/03-authentication/jwt-claims.md)
- [ ] 是否涉及 RBAC 角色定义变更？→ See: [reference/05-rbac/rbac-roles.md](reference/05-rbac/rbac-roles.md)
- [ ] 是否涉及用户表 schema 变更？→ See: [reference/09-data-model/user-table-schema.md](reference/09-data-model/user-table-schema.md)
- [ ] 是否涉及工单回调逻辑变更？→ See: [reference/06-registration-workflow/](reference/06-registration-workflow/) + [reference/07-management-workflow/](reference/07-management-workflow/)
- [ ] 是否涉及权限模块枚举 PermissionModule 变更？→ See: [reference/08-permission-model/permission-architecture.md](reference/08-permission-model/permission-architecture.md)
- [ ] 是否涉及 jenkins_acls/project_acls 表结构变更？→ See: [reference/09-data-model/permission-tables-schema.md](reference/09-data-model/permission-tables-schema.md)

---

## Verify（验证清单）

### RBAC 兼容性检查
- [ ] 角色层级未被破坏：superadmin > admin > normal > third（验证 `reference/05-rbac/rbac-roles.md` 角色层级）
- [ ] "谁注册谁管理"原则未被违反：grep `registered_by_id` 校验逻辑
- [ ] SuperAdmin 始终具有全部权限：所有 CheckPermission 首先判断 superadmin
- [ ] Admin 不可创建/升级 SuperAdmin
- [ ] 注册权限矩阵正确：SuperAdmin→所有角色，Admin→normal/third，Normal→third

### JWT/Session 安全检查
- [ ] JWT 签名算法仍为 HS256（对照 `reference/03-authentication/jwt-claims.md`）
- [ ] Token 有效期未超过 4h
- [ ] Claims 包含必要字段：user_id, username, role, status
- [ ] 仅 status=active 用户可通过校验
- [ ] 账户有效期 account_expires_at 过期检查已实现

### 密码与账户有效期检查
- [ ] 密码传输使用 RSA-OAEP(SHA-256, 2048) 加密（参考 `reference/03-authentication/login-design.md`）
- [ ] 密码存储使用 bcrypt
- [ ] 密码有效期为 3 个月（password_expires_at）
- [ ] 首次登录/密码重置后 must_change_password = true
- [ ] 非 SuperAdmin 创建用户必须设置 account_expires_at
- [ ] 登录时检查账户有效期并返回 account_expire_days 提醒

### 权限模块检查
- [ ] PermissionModule 枚举定义完整且一致（对照 `reference/08-permission-model/permission-architecture.md`）
- [ ] jenkins_acls 层级继承正确（Org→Repo→Branch）（参考 `reference/08-permission-model/jenkins-acls.md`）
- [ ] project_acls 模块代码与 JSONB 映射正确（参考 `reference/08-permission-model/project-acls.md`）
- [ ] user_permission_caches L2 缓存失效逻辑正确
- [ ] L1 内存缓存与 L2 DB 缓存同步清除

### API 契约检查
- [ ] 请求/响应字段向后兼容（对照 `reference/10-api-design/api-endpoints.md`）
- [ ] 错误码未被移除或语义变更
- [ ] 新增字段有默认值（must_change_password, account_expires_at）

### 工单集成检查
- [ ] 注册工单：用户初始状态为 disabled（参考 `reference/06-registration-workflow/registration-workflow.md`）
- [ ] 审批通过回调：ActivateUser 状态变更为 active
- [ ] 撤销回调：DeletePendingUser 删除 status=disabled 的用户
- [ ] 管理工单：ExecuteUserManagement 正确执行 update/enable/disable/delete/reset_password/extend_validity（参考 `reference/07-management-workflow/management-workflow.md`）
- [ ] 工单由用户管理接口内部自动创建（前端不直接调用创建工单接口）

### 验证命令
```bash
# 运行单元测试
go test ./internal/user-auth/... -v

# 检查 RBAC 定义一致性
grep -rn "superadmin\|admin\|normal\|third" --include="*.go" | sort | uniq

# 检查 PermissionModule 使用
grep -rn "PermissionModule\|ModuleJenkins\|ModuleProject" --include="*.go"

# 验证 JWT middleware 与账户有效期检查
grep -rn "account_expires_at\|AccountExpiresAt" --include="*.go"

# 验证工单回调注入
grep -rn "UserStatusUpdater\|WorkflowCreator\|SetUserStatusUpdater" --include="*.go"
```

---

## Execute（执行步骤）

### 1. 认证相关变更 (auth)
```bash
# 1. 定位认证处理器
grep -rn "func.*Login\|func.*Register" --include="*.go"

# 2. 修改认证逻辑（注意 must_change_password 和 account_expires_at 检查）
# 3. 更新登录响应（含 password_expire_days, account_expire_days, must_change_password）
# 4. 验证 RSA 加密流程
go test ./internal/user-auth/service/auth_service_test.go -v
```

### 2. 权限相关变更 (permission)
```bash
# 1. 定位权限检查逻辑
grep -rn "CheckPermission\|CheckHierarchical\|PermissionModule" --include="*.go"

# 2. 修改权限逻辑（注意 jenkins_acls 层级继承、project_acls 模块级）
# 3. 更新权限缓存逻辑（L1 内存 + L2 DB user_permission_caches）
# 4. 验证 Jenkins 权限层级
go test ./internal/user-auth/service/jenkins_permission_service_test.go -v
```

### 3. 用户 CRUD 变更 (user-crud)
```bash
# 1. 修改用户服务（注意 registered_by_id/registered_by_name 设置）
# 2. 设置 account_expires_at（非 SuperAdmin 创建时必须）
# 3. 设置 must_change_password = true（新用户/密码重置）
# 4. 同步更新工单回调 executor
# 5. 更新审计日志记录
go test ./internal/user-auth/service/user_service_test.go -v
```

### 4. 工单集成变更 (workflow)
```bash
# 1. 确认接口注入机制（rmdc-core 初始化时注入）
# 2. 实现 UserStatusUpdater 接口（ActivateUser/DeletePendingUser/ExecuteUserManagement）
# 3. 实现 WorkflowCreator 调用（CreateRegistrationWorkflow/CreateManagementWorkflow）
# 4. 验证工单载荷结构（RegistrationWorkflowPayload/ManagementWorkflowPayload）
# 5. 确保前端不直接调用创建工单接口
```

### 5. 账户有效期变更 (account-validity)
```bash
# 1. 添加/修改 users 表的 account_expires_at 字段
# 2. 修改登录检查逻辑（过期拒绝、7天内提醒）
# 3. 修改用户创建逻辑（根据创建者角色设置有效期选项）
# 4. 实现 extend_validity 管理操作
```

---

## Pitfalls（常见坑）

1. **JWT Claims 变更未同步下游**：修改 claims 字段后，必须通知所有依赖模块更新解析逻辑。参考 `reference/03-authentication/jwt-claims.md` 中的兼容性要求。

2. **RBAC 层级破坏**：admin 能创建 superadmin 是严重安全漏洞。每次角色相关变更必须验证 `reference/05-rbac/rbac-roles.md` 中的层级约束。

3. **密码过期时间未刷新**：修改密码、重置密码、创建用户时必须刷新 `password_expires_at` 并设置 `must_change_password`。参考 `reference/04-user-lifecycle/user-lifecycle.md`。

4. **工单回调状态不一致**：用户注册工单撤销时，必须确认用户仍为 disabled 状态才能删除。参考 `reference/06-registration-workflow/registration-workflow.md` 中的状态映射表。

5. **RSA 密钥轮换影响**：密钥过期后自动生成新密钥，前端缓存的旧公钥将无法加密。参考 `reference/03-authentication/login-design.md` 中的轮换策略。

6. **权限缓存脏读**：修改权限后必须同时清除对应用户的 L1 内存缓存和 L2 DB 缓存。参考 `reference/08-permission-model/jenkins-acls.md` 中的缓存失效逻辑。

7. **账户有效期校验遗漏**：登录流程和 JWT 中间件都需要检查 `account_expires_at`。参考 `reference/04-user-lifecycle/user-lifecycle.md` 中的有效期检查逻辑。

8. **工单接口直接调用**：前端不应直接调用创建工单接口。参考 `reference/10-api-design/api-endpoints.md` 中的重要约束。

---

## Reference 目录结构

```
reference/
├── 01-overview/
│   └── module-overview.md       # 模块概述
├── 02-architecture/
│   ├── module-dependencies.md   # 模块依赖关系
│   ├── interface-injection.md   # 接口注入机制
│   └── tech-stack.md            # 技术栈
├── 03-authentication/
│   ├── login-design.md          # 登录设计
│   └── jwt-claims.md            # JWT Claims 定义
├── 04-user-lifecycle/
│   └── user-lifecycle.md        # 用户生命周期
├── 05-rbac/
│   └── rbac-roles.md            # RBAC 角色矩阵
├── 06-registration-workflow/
│   └── registration-workflow.md # 注册工单流程
├── 07-management-workflow/
│   └── management-workflow.md   # 管理工单流程
├── 08-permission-model/
│   ├── permission-architecture.md  # 统一权限架构
│   ├── jenkins-acls.md             # Jenkins 层级权限
│   ├── project-acls.md             # 项目模块权限
│   └── business-info-registry.md   # 业务信息注册中心
├── 09-data-model/
│   ├── user-table-schema.md        # 用户表 Schema
│   └── permission-tables-schema.md # 权限表 Schema
├── 10-api-design/
│   └── api-endpoints.md         # API 接口清单
└── 11-security/
    └── security-compliance.md   # 安全与合规
```

---

## 相关文件速查

| 用途 | 路径 |
|:---|:---|
| 模块概述 | [reference/01-overview/module-overview.md](reference/01-overview/module-overview.md) |
| 模块依赖 | [reference/02-architecture/module-dependencies.md](reference/02-architecture/module-dependencies.md) |
| 接口注入 | [reference/02-architecture/interface-injection.md](reference/02-architecture/interface-injection.md) |
| 登录设计 | [reference/03-authentication/login-design.md](reference/03-authentication/login-design.md) |
| JWT Claims | [reference/03-authentication/jwt-claims.md](reference/03-authentication/jwt-claims.md) |
| 用户生命周期 | [reference/04-user-lifecycle/user-lifecycle.md](reference/04-user-lifecycle/user-lifecycle.md) |
| RBAC 角色 | [reference/05-rbac/rbac-roles.md](reference/05-rbac/rbac-roles.md) |
| 注册工单 | [reference/06-registration-workflow/registration-workflow.md](reference/06-registration-workflow/registration-workflow.md) |
| 管理工单 | [reference/07-management-workflow/management-workflow.md](reference/07-management-workflow/management-workflow.md) |
| 权限架构 | [reference/08-permission-model/permission-architecture.md](reference/08-permission-model/permission-architecture.md) |
| Jenkins 权限 | [reference/08-permission-model/jenkins-acls.md](reference/08-permission-model/jenkins-acls.md) |
| 项目权限 | [reference/08-permission-model/project-acls.md](reference/08-permission-model/project-acls.md) |
| 用户表 Schema | [reference/09-data-model/user-table-schema.md](reference/09-data-model/user-table-schema.md) |
| 权限表 Schema | [reference/09-data-model/permission-tables-schema.md](reference/09-data-model/permission-tables-schema.md) |
| API 端点 | [reference/10-api-design/api-endpoints.md](reference/10-api-design/api-endpoints.md) |
| 安全合规 | [reference/11-security/security-compliance.md](reference/11-security/security-compliance.md) |
| 认证处理器骨架 | [examples/auth-handler-skeleton.go](examples/auth-handler-skeleton.go) |
| 权限检查骨架 | [examples/permission-check-skeleton.go](examples/permission-check-skeleton.go) |
| 工单回调示例 | [examples/workflow-callback-skeleton.go](examples/workflow-callback-skeleton.go) |
| 验证脚本 | [scripts/verify-user-auth.sh](scripts/verify-user-auth.sh) |