ProjectAGiPrompt/1-AgentSkills/developing-user-auth/SKILL.md

name, description, allowed-tools, argument-hint

name	description	allowed-tools	argument-hint
developing-user-auth	指导开发 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.	Read Glob Grep Bash Edit Write	$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
• 是否涉及 RBAC 角色定义变更？→ See: reference/05-rbac/rbac-roles.md
• 是否涉及用户表 schema 变更？→ See: reference/09-data-model/user-table-schema.md
• 是否涉及工单回调逻辑变更？→ See: reference/06-registration-workflow/ + reference/07-management-workflow/
• 是否涉及权限模块枚举 PermissionModule 变更？→ See: reference/08-permission-model/permission-architecture.md
• 是否涉及 jenkins_acls/project_acls 表结构变更？→ See: 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）
• 工单由用户管理接口内部自动创建（前端不直接调用创建工单接口）

验证命令

# 运行单元测试
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)

# 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)

# 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)

# 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)

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

5. 账户有效期变更 (account-validity)

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