zeaslity/ProjectAGiPrompt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新RMDC系统的模块SKILL

Browse Source
This commit is contained in:
zeaslity
2026-02-02 15:06:28 +08:00
parent 93624efdab
commit a02ac14481
89 changed files with 8101 additions and 2417 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
8-CMII-RMDC/4-rmdc-project-management/2-rmdc-project-management-DDS.md
View File

@@ -999,4 +999,4 @@ type AuthorizationInfo struct {
| [项目管理PRD](1-rmdc-project-management-PRD.md) | 产品需求文档 |
| [项目状态说明](4-project-状态说明.md) | 状态转换说明 |
| [工单模块DDS](../7-rmdc-work-procedure/1-rmdc-work-procedure-DDS.md) | 工单流程设计 |
| [用户权限DDS](../9-rmdc-user-auth/1-user-auth-DDS.md) | 用户权限设计 |
| [用户权限DDS](../9-rmdc-user-auth/1-user-auth-PRD.md) | 用户权限设计 |

361
8-CMII-RMDC/4-rmdc-project-management/3-china-province-city copy.md Normal file
View File

@@ -0,0 +1,361 @@
## 省份及地级市列表
**河北省**
河北省-石家庄市
河北省-唐山市
河北省-秦皇岛市
河北省-邯郸市
河北省-邢台市
河北省-保定市
河北省-张家口市
河北省-承德市
河北省-沧州市
河北省-廊坊市
河北省-衡水市
**山西省**
山西省-太原市
山西省-大同市
山西省-阳泉市
山西省-长治市
山西省-晋城市
山西省-朔州市
山西省-晋中市
山西省-运城市
山西省-忻州市
山西省-临汾市
山西省-吕梁市
**内蒙古自治区**
内蒙古自治区-呼和浩特市
内蒙古自治区-包头市
内蒙古自治区-乌海市
内蒙古自治区-赤峰市
内蒙古自治区-通辽市
内蒙古自治区-鄂尔多斯市
内蒙古自治区-呼伦贝尔市
内蒙古自治区-巴彦淖尔市
内蒙古自治区-乌兰察布市
**辽宁省**
辽宁省-沈阳市
辽宁省-大连市
辽宁省-鞍山市
辽宁省-抚顺市
辽宁省-本溪市
辽宁省-丹东市
辽宁省-锦州市
辽宁省-营口市
辽宁省-阜新市
辽宁省-辽阳市
辽宁省-盘锦市
辽宁省-铁岭市
辽宁省-朝阳市
辽宁省-葫芦岛市
**吉林省**
吉林省-长春市
吉林省-吉林市
吉林省-四平市
吉林省-辽源市
吉林省-通化市
吉林省-白山市
吉林省-松原市
吉林省-白城市
**黑龙江省**
黑龙江省-哈尔滨市
黑龙江省-齐齐哈尔市
黑龙江省-鸡西市
黑龙江省-鹤岗市
黑龙江省-双鸭山市
黑龙江省-大庆市
黑龙江省-伊春市
黑龙江省-佳木斯市
黑龙江省-七台河市
黑龙江省-牡丹江市
黑龙江省-黑河市
黑龙江省-绥化市
**江苏省**
江苏省-南京市
江苏省-无锡市
江苏省-徐州市
江苏省-常州市
江苏省-苏州市
江苏省-南通市
江苏省-连云港市
江苏省-淮安市
江苏省-盐城市
江苏省-扬州市
江苏省-镇江市
江苏省-泰州市
江苏省-宿迁市
**浙江省**
浙江省-杭州市
浙江省-宁波市
浙江省-温州市
浙江省-嘉兴市
浙江省-湖州市
浙江省-绍兴市
浙江省-金华市
浙江省-衢州市
浙江省-舟山市
浙江省-台州市
浙江省-丽水市
**安徽省**
安徽省-合肥市
安徽省-芜湖市
安徽省-蚌埠市
安徽省-淮南市
安徽省-马鞍山市
安徽省-淮北市
安徽省-铜陵市
安徽省-安庆市
安徽省-黄山市
安徽省-滁州市
安徽省-阜阳市
安徽省-宿州市
安徽省-六安市
安徽省-亳州市
安徽省-池州市
安徽省-宣城市
**福建省**
福建省-福州市
福建省-厦门市
福建省-三明市
福建省-莆田市
福建省-泉州市
福建省-漳州市
福建省-南平市
福建省-龙岩市
福建省-宁德市
**江西省**
江西省-南昌市
江西省-景德镇市
江西省-萍乡市
江西省-九江市
江西省-新余市
江西省-鹰潭市
江西省-赣州市
江西省-吉安市
江西省-宜春市
江西省-抚州市
江西省-上饶市
**山东省**
山东省-济南市
山东省-青岛市
山东省-淄博市
山东省-枣庄市
山东省-东营市
山东省-烟台市
山东省-潍坊市
山东省-济宁市
山东省-泰安市
山东省-威海市
山东省-日照市
山东省-临沂市
山东省-德州市
山东省-聊城市
山东省-滨州市
山东省-菏泽市
**河南省**
河南省-郑州市
河南省-开封市
河南省-洛阳市
河南省-平顶山市
河南省-安阳市
河南省-鹤壁市
河南省-新乡市
河南省-焦作市
河南省-濮阳市
河南省-许昌市
河南省-漯河市
河南省-三门峡市
河南省-南阳市
河南省-商丘市
河南省-信阳市
河南省-周口市
河南省-驻马店市
**湖北省**
湖北省-武汉市
湖北省-黄石市
湖北省-十堰市
湖北省-宜昌市
湖北省-襄阳市
湖北省-鄂州市
湖北省-荆门市
湖北省-孝感市
湖北省-荆州市
湖北省-黄冈市
湖北省-咸宁市
湖北省-随州市
**湖南省**
湖南省-长沙市
湖南省-株洲市
湖南省-湘潭市
湖南省-衡阳市
湖南省-邵阳市
湖南省-岳阳市
湖南省-常德市
湖南省-张家界市
湖南省-益阳市
湖南省-郴州市
湖南省-永州市
湖南省-怀化市
湖南省-娄底市
**广东省**
广东省-广州市
广东省-韶关市
广东省-深圳市
广东省-珠海市
广东省-汕头市
广东省-佛山市
广东省-江门市
广东省-湛江市
广东省-茂名市
广东省-肇庆市
广东省-惠州市
广东省-梅州市
广东省-汕尾市
广东省-河源市
广东省-阳江市
广东省-清远市
广东省-东莞市
广东省-中山市
广东省-潮州市
广东省-揭阳市
广东省-云浮市
**广西壮族自治区**
广西壮族自治区-南宁市
广西壮族自治区-柳州市
广西壮族自治区-桂林市
广西壮族自治区-梧州市
广西壮族自治区-北海市
广西壮族自治区-防城港市
广西壮族自治区-钦州市
广西壮族自治区-贵港市
广西壮族自治区-玉林市
广西壮族自治区-百色市
广西壮族自治区-贺州市
广西壮族自治区-河池市
广西壮族自治区-来宾市
广西壮族自治区-崇左市
**海南省**
海南省-海口市
海南省-三亚市
海南省-三沙市
海南省-儋州市
**四川省**
四川省-成都市
四川省-自贡市
四川省-攀枝花市
四川省-泸州市
四川省-德阳市
四川省-绵阳市
四川省-广元市
四川省-遂宁市
四川省-内江市
四川省-乐山市
四川省-南充市
四川省-眉山市
四川省-宜宾市
四川省-广安市
四川省-达州市
四川省-雅安市
四川省-巴中市
四川省-资阳市
**贵州省**
贵州省-贵阳市
贵州省-六盘水市
贵州省-遵义市
贵州省-安顺市
贵州省-毕节市
贵州省-铜仁市
**云南省**
云南省-昆明市
云南省-曲靖市
云南省-玉溪市
云南省-保山市
云南省-昭通市
云南省-丽江市
云南省-普洱市
云南省-临沧市
**西藏自治区**
西藏自治区-拉萨市
西藏自治区-日喀则市
西藏自治区-昌都市
西藏自治区-林芝市
西藏自治区-山南市
西藏自治区-那曲市
**陕西省**
陕西省-西安市
陕西省-铜川市
陕西省-宝鸡市
陕西省-咸阳市
陕西省-渭南市
陕西省-汉中市
陕西省-延安市
陕西省-榆林市
陕西省-安康市
陕西省-商洛市
**甘肃省**
甘肃省-兰州市
甘肃省-嘉峪关市
甘肃省-金昌市
甘肃省-白银市
甘肃省-天水市
甘肃省-武威市
甘肃省-张掖市
甘肃省-平凉市
甘肃省-酒泉市
甘肃省-庆阳市
甘肃省-定西市
甘肃省-陇南市
**青海省**
青海省-西宁市
青海省-海东市
**宁夏回族自治区**
宁夏回族自治区-银川市
宁夏回族自治区-石嘴山市
宁夏回族自治区-吴忠市
宁夏回族自治区-固原市
宁夏回族自治区-中卫市
**新疆维吾尔自治区**
新疆维吾尔自治区-乌鲁木齐市
新疆维吾尔自治区-克拉玛依市
新疆维吾尔自治区-吐鲁番市
新疆维吾尔自治区-哈密市
**直辖市(与省平级)**
北京市
天津市
上海市
重庆市
**特别行政区**
香港特别行政区
澳门特别行政区
**台湾省**
台湾省

0
8-CMII-RMDC/9-rmdc-user-auth/1-user-auth-DDS.md → 8-CMII-RMDC/9-rmdc-user-auth/1-user-auth-PRD.md
View File

954
8-CMII-RMDC/9-rmdc-user-auth/2-user-auth-DDS.md Normal file
View File

@@ -0,0 +1,954 @@
# RMDC 用户认证模块详细设计说明书 (DDS)
**产品名称**: RMDC 用户认证模块 (rmdc-user-auth)
**版本**: v2.0
**编制日期**: 2026-01-27
---
## 1. 概述
### 1.1 模块定位
`rmdc-user-auth` 提供 RMDC 统一的用户认证、账户生命周期管理与权限服务，支持 RSA 加密登录、JWT 鉴权、密码过期策略，以及通过工单驱动的用户注册/管理审批流程。
### 1.2 核心职责
1. **身份认证**：RSA-OAEP 密码加密 + bcrypt 校验，颁发 4h 有效的 JWT。
2. **账号管理**：用户 CRUD、密码修改、个人资料更新，支持密码过期、首次登录强制改密与状态控制（active/locked/disabled）。
3. **审批工作流集成**：用户注册/管理通过 `rmdc-work-procedure` 工单审批，遵循"谁注册谁管理"。
4. **权限服务**：
1. Jenkins 分支层级权限（Org/Repo/Branch）权限，对外暴露权限检查接口。
2. Project 项目权限（数据权限）权限
3. DeliveryUpdate 微服务更新权限
5. **系统配置**：RSA 密钥对、登录策略、注册开关等配置的存取与缓存。
### 1.3 版本修订历史
| 版本 | 日期 | 修订内容 |
|:---|:---|:---|
| v1.0 | 2026-01-23 | 基于现有代码首次形成 DDS，覆盖认证、工单、权限与数据模型 |
| v2.0 | 2026-01-27 | 新增用户有效期字段、强制改密机制、用户注册/管理工单流程详细设计、模块依赖关系流程图 |
---
## 2. 系统架构
### 2.1 模块依赖关系
```mermaid
graph TB
subgraph 核心层
Core[rmdc-core<br/>API Gateway]
end
subgraph 用户与权限
UA[rmdc-user-auth<br/>用户认证/权限]
end
subgraph 业务协作
PM[rmdc-project-management<br/>项目管理]
WP[rmdc-work-procedure<br/>工单流程]
JB[rmdc-jenkins-branch-dac<br/>Jenkins分支权限]
end
subgraph 基础设施
CMN[rmdc-common<br/>公共模块]
Aud[rmdc-audit-log<br/>审计日志]
end
Core --> UA
Core --> PM
Core --> WP
UA -->|用户注册/管理工单| WP
UA -->|Jenkins资源查询| JB
UA --> CMN
UA --> Aud
PM -->|用户鉴权/查询| UA
PM -->|项目权限管理| UA
PM -->|项目工单| WP
WP -->|用户状态回调| UA
WP -->|项目状态回调| PM
```
### 2.2 用户模块与工单模块依赖关系详图
```mermaid
graph TB
subgraph rmdc_core["rmdc-core (入口层)"]
INIT[模块初始化]
end
subgraph rmdc_user_auth["rmdc-user-auth (用户认证层)"]
UH[UserHandler<br/>用户接口]
UWH[UserWorkflowHandler<br/>用户工单接口]
US[UserService<br/>用户服务]
URS[UserRegistrationService<br/>注册工单服务]
UMS[UserManagementService<br/>管理工单服务]
end
subgraph rmdc_work_procedure["rmdc-work-procedure (工单层)"]
WH[WorkflowHandler<br/>工单接口]
WS[WorkflowService<br/>工单服务]
WC[WorkflowCallbacks<br/>状态回调]
end
INIT -->|注入用户状态回调| WS
INIT -->|注入工单创建器| US
UH --> US
UWH --> URS
UWH --> UMS
URS -->|创建注册工单| WS
UMS -->|创建管理工单| WS
WC -->|审批通过: 激活用户| US
WC -->|审批打回: 通知修改| URS
WC -->|撤销: 删除待审批用户| US
WC -->|管理审批通过: 执行变更| UMS
```
### 2.3 接口注入机制
采用 **接口注入（依赖注入）** 方式实现模块间回调，与项目管理模块保持一致的架构模式。
#### 2.3.1 工单模块回调用户模块的接口
```go
// UserStatusUpdater 用户状态更新接口
// 由 rmdc-core 在初始化时注入，工单模块状态变更时调用
type UserStatusUpdater interface {
// UpdateUserStatus 更新用户状态（审批通过时激活）
UpdateUserStatus(userID int64, status string) error
// ActivateUser 激活用户（注册审批通过）
ActivateUser(userID int64) error
// DeletePendingUser 删除待审批用户（工单撤销时）
DeletePendingUser(userID int64) error
// ExecuteUserManagement 执行用户管理操作（管理审批通过）
ExecuteUserManagement(userID int64, action string, payload map[string]interface{}) error
}
```
#### 2.3.2 用户模块调用工单模块的接口
```go
// WorkflowCreator 工单创建接口
// 由 rmdc-core 在初始化时注入，用户模块通过此接口创建工单
type WorkflowCreator interface {
// CreateRegistrationWorkflow 创建用户注册工单
CreateRegistrationWorkflow(ctx context.Context, req *RegistrationWorkflowRequest) (string, error)
// CreateManagementWorkflow 创建用户管理工单
CreateManagementWorkflow(ctx context.Context, req *ManagementWorkflowRequest) (string, error)
}
```
### 2.4 技术栈
- Gin (HTTP 路由)
- GORM (ORM，依赖 `models.DatabaseConnections` 提供多库连接：User/Jenkins/Core/Workflow)
- JWT (HS256)
- RSA-OAEP (2048) 前端密码加密，密钥 30 天轮换
- bcrypt (密码存储)
- 内部模块依赖：`rmdc-work-procedure`（工单）、`rmdc-jenkins-branch-dac`（Jenkins 资源）、`rmdc-common`（日志、返回码、模型）
### 2.5 路由与中间件分层
- `/api/auth/*`：免 token，含获取 RSA 公钥、登录、注册。
- `/api/users`、`/api/user`、`/api/permissions`：需 `AuthMiddleware(jwtSecret)` 校验 JWT，部分再叠加 `RequireAdmin()`。
- 中间件：
- `AuthMiddleware`：解析 Bearer JWT，校验签名和用户状态为 `active`，注入用户上下文。
- `RequireAdmin`：判定角色包含 `admin` 字样（superadmin/admin）。
### 2.6 组件关系
- Handler 层：`auth_handler`、`user_handler`、`permission_handler` 注册 HTTP 路由。
- Service 层：`AuthService`、`RSAService`、`UserService`、`JenkinsPermissionService`、`SystemConfigService`、注册/管理工单服务。
- DAO 层：`UserDao`、`RSAKeypairDao`、`JenkinsPermissionDao`、`BasePermissionDao`、`SystemConfigDao`、`JenkinsDao`。
- 公共接口：`pkg/permission.PermissionChecker` 对外暴露权限检查，供其他模块调用。
---
## 3. 认证与登录设计
### 3.1 登录流程（RSA + JWT）
1. 前端调用 `GET /api/auth/rsa/public-key` 获取当前有效公钥（30 天有效，过期自动轮换）。
2. 前端用 RSA-OAEP(SHA-256, 2048) 加密密码，提交 `POST /api/auth/login`，字段 `encrypted_password`。
3. 后端 `RSAService` 解密，`AuthService` 用 bcrypt 校验 `users.password_hash`。
4. 生成 HS256 JWT，默认有效期 4h，Claims 包含用户基础信息与 `status`。
5. 返回 Token 与用户信息，并返回以下标识：
- `must_change_password`: 首次登录或密码重置后需强制修改密码
- `password_expire_days`: 密码剩余有效天数（7 天内提示）
- `account_expire_days`: 账户剩余有效天数（7 天内提示）
### 3.2 密钥与密码策略
- RSA 密钥：`rsa_keypairs` 表存储 PEM，对外只暴露公钥；过期自动生成新对，异步清理过期数据。
- 密码哈希：bcrypt 默认成本；密码有效期 3 个月（注册/重置/直改都会刷新过期时间）。
- 账户状态：active/locked/disabled；JWT 校验时必须 active。
- 首次登录强制改密：新注册用户或重置密码后，`must_change_password` 标识为 true。
- 登录失败计数：字段存在，逻辑留有 TODO（未实现锁定策略）。
### 3.3 JWT 中间件行为
- 解析 Authorization: Bearer <token>，校验签名与过期。
- 校验 `claims.Status == "active"`，否则 401。
- 注入上下文键：`user_id/username/english_name/phone/group_name/role/dev_role/status`。
### 3.4 缺省/限制
- 无刷新接口；Token 过期需重新登录。
- 无服务器端注销接口（前端丢弃 Token）。
---
## 4. 用户生命周期管理
### 4.1 用户状态定义
| 状态 | 说明 | 触发条件 |
|:---|:---|:---|
| `disabled` | 待审批状态 | 用户注册后默认状态 |
| `active` | 正常激活 | 注册工单审批通过 |
| `locked` | 临时锁定 | 登录失败次数过多 / 管理员手动锁定 |
### 4.2 用户生命周期状态机
```mermaid
stateDiagram-v2
[*] --> disabled: 用户注册
disabled --> disabled: 保存草稿
disabled --> disabled: 工单打回，等待修改
disabled --> active: 注册工单审批通过
disabled --> [*]: 工单撤销，删除用户
active --> active: 正常使用
active --> active: 信息更新
active --> locked: 登录失败锁定
active --> disabled: 管理员禁用
active --> [*]: 管理员删除
locked --> active: 解锁
locked --> disabled: 管理员禁用
note right of disabled: 用户刚注册，等待审批
note right of active: 正常使用状态
note right of locked: 临时锁定，可解锁
```
### 4.3 用户有效期机制
#### 4.3.1 有效期设置规则
| 用户类型 | 有效期选项 | 默认值 | 说明 |
|:---|:---|:---|:---|
| SuperAdmin 创建的用户 | 无限制 / 自定义 | 永久 | SuperAdmin 可设置任意有效期 |
| Admin 创建的用户 | 1个月/3个月/6个月/1年 | 3个月 | 必须设置有效期 |
| Normal 创建的用户 | 1个月/3个月/6个月/1年 | 3个月 | 必须设置有效期 |
#### 4.3.2 有效期字段设计
```go
// 用户表新增字段
AccountExpiresAt *time.Time `json:"account_expires_at"` // 账户有效期
```
#### 4.3.3 有效期检查逻辑
1. **登录时检查**：若 `account_expires_at` 不为空且已过期，拒绝登录并返回账户已过期提示
2. **接口检查**：JWT 中间件校验用户状态时，同时检查账户有效期
3. **提前提醒**：账户有效期剩余 7 天内，登录时返回提醒信息
### 4.4 强制修改密码机制
#### 4.4.1 触发条件
| 条件 | 字段标识 | 处理方式 |
|:---|:---|:---|
| 首次登录 | `must_change_password = true` | 登录成功后跳转改密页面 |
| 密码重置后 | `must_change_password = true` | 使用临时密码登录后强制改密 |
| 密码过期 | `password_expires_at` 已过期 | 拒绝登录，提示密码已过期 |
#### 4.4.2 密码过期时间线
```mermaid
flowchart TB
A["创建用户 / 重置密码"]
B["password_expires_at = now + 90天\nmust_change_password = true"]
C["首次登录"]
D["强制修改密码"]
E["修改密码后：\npassword_expires_at = now + 90天\nmust_change_password = false"]
F["正常使用"]
G["第83天：提醒"]
H["第90天：强制过期"]
A --> B --> C --> D --> E --> F --> G --> H
```
---
## 5. 用户注册与管理权限
### 5.1 角色与注册/管理权限矩阵
| 操作者角色 | 可注册角色 | 可管理范围 | 说明 |
|:---|:---|:---|:---|
| SuperAdmin | superadmin/admin/normal/third | 所有用户 | 完全权限 |
| Admin | normal/third | 自己注册的用户 | 遵循"谁注册谁管理" |
| Normal | third | 自己注册的用户 | 仅可注册三方用户 |
| Third | - | - | 无注册和管理权限 |
### 5.2 管理操作权限矩阵
| 操作 | SuperAdmin | Admin | Normal | Third |
|:---|:---|:---|:---|:---|
| 修改用户信息 | ✅ 所有用户 | ✅ 自己注册的 | ✅ 自己注册的 | ❌ |
| 启用用户 | ✅ 所有用户 | ✅ 自己注册的 | ✅ 自己注册的 | ❌ |
| 禁用用户 | ✅ 所有用户 | ✅ 自己注册的 | ✅ 自己注册的 | ❌ |
| 删除用户 | ✅ 所有用户 | ✅ 自己注册的 | ✅ 自己注册的 | ❌ |
| 重置密码 | ✅ 所有用户 | ✅ 自己注册的 | ❌ | ❌ |
| 延长有效期 | ✅ 所有用户 | ❌ | ❌ | ❌ |
### 5.3 "谁注册谁管理"原则
1. **注册关系记录**：用户表中 `registered_by_id` 记录注册人 ID
2. **权限检查规则**：
- SuperAdmin：可管理所有用户
- Admin/Normal：只能管理 `registered_by_id == current_user_id` 的用户
3. **审批归属**：所有用户注册/管理工单由 SuperAdmin 审批
---
## 6. 用户注册工单流程
### 6.1 工单流程概述
```mermaid
sequenceDiagram
participant User as 注册发起人
participant UA as rmdc-user-auth
participant WP as rmdc-work-procedure
participant SA as SuperAdmin
User->>UA: POST /api/users (创建用户)
UA->>UA: 创建用户记录<br/>(status=disabled, 默认密码)
UA->>WP: CreateWorkflow(user_registration)
WP-->>UA: workflow_id
UA-->>User: 返回成功，工单ID
WP->>SA: 通知：新用户注册待审批
alt 审批通过
SA->>WP: POST /api/workflow/approve
WP->>UA: ActivateUser(user_id)
UA->>UA: status = active
UA-->>WP: success
WP->>User: 通知：用户注册已通过
else 审批打回
SA->>WP: POST /api/workflow/return
WP->>User: 通知：请修改用户信息
User->>UA: PUT /api/users/:id (修改信息)
User->>WP: POST /api/workflow/resubmit
else 撤销
User->>WP: POST /api/workflow/revoke
WP->>UA: DeletePendingUser(user_id)
UA->>UA: DELETE users WHERE status=disabled
end
```
### 6.2 工单状态与用户状态映射
| 工单事件 | 工单状态 | 用户状态 | 说明 |
|:---|:---|:---|:---|
| create | pending_review | disabled | 创建用户并提交审核 |
| approve | approved | active | 审核通过，激活用户 |
| return | returned | disabled (保持) | 打回修改，用户状态不变 |
| resubmit | pending_review | disabled (保持) | 重新提交审核 |
| revoke | revoked | (删除) | 撤销工单，删除待审批用户 |
### 6.3 注册工单业务载荷
```go
// RegistrationWorkflowPayload 注册工单业务载荷
type RegistrationWorkflowPayload struct {
TargetUserID int64 `json:"target_user_id"` // 被注册用户ID
TargetUsername string `json:"target_username"` // 被注册用户名
TargetRole string `json:"target_role"` // 被注册用户角色
RegisteredByID int64 `json:"registered_by_id"` // 注册人ID
RegisteredByName string `json:"registered_by_name"` // 注册人姓名
AccountExpiresAt time.Time `json:"account_expires_at"` // 账户有效期
RegistrationReason string `json:"registration_reason"` // 注册原因
}
```
### 6.4 注册接口设计要点
1. **不暴露密码设置**：注册接口不接收密码参数，后端自动生成默认密码（如 `Rmdc@2026`）
2. **必须设置有效期**：非 SuperAdmin 创建用户时，必须选择有效期（1个月/3个月/6个月/1年）
3. **自动创建工单**：用户创建接口内部调用工单模块创建审批工单
4. **工单初始状态**：直接进入 `pending_review`，由 SuperAdmin 审批
---
## 7. 用户管理工单流程
### 7.1 管理操作类型
| 操作类型代码 | 操作名称 | 说明 | 需要审批 |
|:---|:---|:---|:---|
| `update` | 修改用户信息 | 修改基本信息（姓名、邮箱等） | 是 |
| `enable` | 启用用户 | 将 disabled 用户改为 active | 是 |
| `disable` | 禁用用户 | 将 active 用户改为 disabled | 是 |
| `delete` | 删除用户 | 软删除用户 | 是 |
| `reset_password` | 重置密码 | 重置为默认密码 | 是 |
| `extend_validity` | 延长有效期 | 延长账户有效期 | 是 |
### 7.2 工单流程
> **重要**：前端不允许直接调用创建工单接口，工单由用户管理接口（如 `PUT /api/users/:id`）内部自动创建。
```mermaid
sequenceDiagram
participant Operator as 操作人
participant UA as rmdc-user-auth
participant WP as rmdc-work-procedure
participant SA as SuperAdmin
Operator->>UA: PUT /api/users/:id (修改用户信息)
Note right of Operator: 或 POST /api/users/:id/enable|disable|delete
UA->>UA: CheckManagementPermission
UA->>UA: 记录原始数据快照
UA->>WP: CreateWorkflow(user_management)
WP-->>UA: workflow_id
UA-->>Operator: 返回成功，工单ID
WP->>SA: 通知：用户管理待审批
alt 审批通过
SA->>WP: POST /api/workflow/approve
WP->>UA: ExecuteUserManagement(action, payload)
UA->>UA: 执行对应操作(update/enable/disable/delete)
UA-->>WP: success
WP->>Operator: 通知：管理操作已通过
else 审批打回
SA->>WP: POST /api/workflow/return
WP->>Operator: 通知：请重新提交
end
```
### 7.3 管理工单业务载荷
```go
// ManagementWorkflowPayload 管理工单业务载荷
type ManagementWorkflowPayload struct {
TargetUserID int64 `json:"target_user_id"` // 目标用户ID
TargetUsername string `json:"target_username"` // 目标用户名
ActionType string `json:"action_type"` // 操作类型
OperatorID int64 `json:"operator_id"` // 操作人ID
OperatorName string `json:"operator_name"` // 操作人姓名
OriginalData map[string]interface{} `json:"original_data"` // 原始数据快照
ModifiedData map[string]interface{} `json:"modified_data"` // 修改后数据
Reason string `json:"reason"` // 操作原因
}
```
### 7.4 管理操作执行器
```go
// UserManagementExecutor 用户管理执行器
type UserManagementExecutor interface {
// UpdateUserInfo 更新用户信息
UpdateUserInfo(userID int64, payload map[string]interface{}) error
// EnableUser 启用用户
EnableUser(userID int64) error
// DisableUser 禁用用户
DisableUser(userID int64) error
// DeleteUser 删除用户
DeleteUser(userID int64) error
// ResetPassword 重置密码
ResetPassword(userID int64) error
// ExtendValidity 延长有效期
ExtendValidity(userID int64, newExpiresAt time.Time) error
}
```
---
## 8. 权限模型
### 8.1 统一权限架构
RMDC 系统采用**专用权限表**的设计模式，针对不同业务场景使用独立的权限表结构，以满足复杂的权限控制需求。同时定义统一的权限模块枚举，便于扩展和维护。
#### 8.1.1 权限模块枚举 (PermissionModule)
```go
// PermissionModule 权限模块枚举
type PermissionModule string
const (
// 用户模块权限
ModuleUserRegister PermissionModule = "user_register" // 用户注册
ModuleUserManage PermissionModule = "user_manage" // 用户管理
ModuleUserPermission PermissionModule = "user_permission" // 用户权限管理
// 项目模块权限
ModuleProjectCreate PermissionModule = "project_create" // 项目创建
ModuleProjectView PermissionModule = "project_view" // 项目查看
ModuleProjectEdit PermissionModule = "project_edit" // 项目编辑
ModuleProjectExport PermissionModule = "project_export" // 项目导出
ModuleProjectAuth PermissionModule = "project_auth" // 项目授权管理
// Jenkins 模块权限
ModuleJenkinsView PermissionModule = "jenkins_view" // Jenkins 查看
ModuleJenkinsBuild PermissionModule = "jenkins_build" // Jenkins 构建
ModuleJenkinsManage PermissionModule = "jenkins_manage" // Jenkins 权限管理
// 微服务更新模块权限
ModuleDeliveryView PermissionModule = "delivery_view" // 微服务查看
ModuleDeliveryUpdate PermissionModule = "delivery_update" // 微服务更新
// 工单模块权限
ModuleWorkflowView PermissionModule = "workflow_view" // 工单查看
ModuleWorkflowApprove PermissionModule = "workflow_approve" // 工单审批
)
// PermissionModuleInfo 模块信息
type PermissionModuleInfo struct {
Code PermissionModule `json:"code"` // 模块代码
Name string `json:"name"` // 模块名称
Description string `json:"description"` // 模块描述
ACLTable string `json:"acl_table"` // 关联的ACL表
}
// 模块注册表
var PermissionModules = map[PermissionModule]PermissionModuleInfo{
ModuleJenkinsView: {Code: ModuleJenkinsView, Name: "Jenkins查看", ACLTable: "jenkins_acls"},
ModuleJenkinsBuild: {Code: ModuleJenkinsBuild, Name: "Jenkins构建", ACLTable: "jenkins_acls"},
ModuleProjectView: {Code: ModuleProjectView, Name: "项目查看", ACLTable: "project_acls"},
ModuleProjectEdit: {Code: ModuleProjectEdit, Name: "项目编辑", ACLTable: "project_acls"},
// ... 其他模块
}
```
#### 8.1.2 权限表概览
| 权限类型 | 权限表 | 权限粒度 | 说明 |
|:---|:---|:---|:---|
| **Jenkins 权限** | `jenkins_acls` | Org/Repo/Branch 层级 | 支持层级继承的 CI/CD 权限 |
| **项目权限** | `project_acls` | 项目模块级 | 项目信息访问权限 |
| **用户权限缓存** | `user_permission_caches` | 用户维度 | 用户所有权限的 L2 缓存树 |
#### 8.1.3 权限检查通用规则
```go
// 权限检查通用规则:
// 1. SuperAdmin 拥有所有权限，直接放行
// 2. 根据 PermissionModule 分流到对应的 ACL 表进行检查
// 3. 权限检查结果存入 L1 内存缓存和 L2 DB 缓存，提升性能
// 4. 权限变更时同时清除 L1 和 L2 缓存
```
### 8.2 Jenkins 层级权限 (jenkins_acls)
#### 8.2.1 层级结构
```
Organization (组织)
└── Repository (仓库)
└── Branch (分支)
```
#### 8.2.2 设计原则
- **层级继承**：上级权限可覆盖下级（如 Org 级权限覆盖其下所有 Repo/Branch）
- **存储最小化**：一条记录可覆盖子层级，减少数据冗余
- **权限类型**：`can_view`（查看，对应 `jenkins_view`）、`can_build`（构建，对应 `jenkins_build`）
#### 8.2.3 权限表设计 (jenkins_acls)
| 字段 | 说明 |
|:---|:---|
| `user_id` | 用户 ID |
| `organization_folder` | 组织文件夹（必填） |
| `repository_name` | 仓库名称（可空，空表示 Org 级权限） |
| `branch_name` | 分支名称（可空，空表示 Repo 级权限） |
| `permission_level` | 权限层级：org/repo/branch |
| `can_view` | 是否可查看 |
| `can_build` | 是否可构建 |
| `granted_by` | 授权人 ID |
| `granted_at` | 授权时间 |
#### 8.2.4 权限缓存机制
- **L1 内存缓存**：`permissionCache`，进程内高速缓存
- **L2 DB 缓存**：`user_permission_caches` 表，存储用户所有权限的缓存树 JSON
- **懒加载接口**：按 organizations → repositories → branches 逐级加载
- **缓存失效**：权限变更时同时清除 L1 和 L2 缓存
#### 8.2.5 权限检查逻辑
```go
// CheckHierarchicalPermission 检查层级权限
// 1. 先检查 Branch 级权限
// 2. 若无则检查 Repo 级权限
// 3. 若无则检查 Org 级权限
// 4. 支持 can_build 需求判断（build 需要 view + build 两个权限）
```
### 8.3 BusinessInfoRegistry 注册中心
权限模块需要查询业务模块信息（如项目填写人），但不应直接依赖具体业务模块。采用**统一注册机制**解决模块依赖。
```mermaid
graph TB
subgraph rmdc_core["rmdc-core (入口层)"]
INIT[模块初始化]
end
subgraph rmdc_user_auth["rmdc-user-auth (权限层)"]
REG[BusinessInfoRegistry<br/>业务信息注册中心]
PS[ProjectPermissionService]
JS[JenkinsPermissionService]
end
subgraph business["业务模块层"]
PM[rmdc-project-management]
JB[rmdc-jenkins-branch-dac]
end
INIT -->|注册业务查询器| REG
INIT -->|注入权限检查器| PM
INIT -->|注入权限检查器| JB
PS --> REG
JS --> REG
REG -.->|查询业务信息| PM
REG -.->|查询Jenkins信息| JB
```
#### 8.3.1 注册接口定义
```go
// BusinessInfoQuerier 业务信息查询接口（通用基类）
type BusinessInfoQuerier interface {
GetModuleCode() string
}
// ProjectInfoQuerier 项目信息查询接口
type ProjectInfoQuerier interface {
BusinessInfoQuerier
GetProjectFillerID(ctx context.Context, projectID string) (int64, error)
}
// JenkinsInfoQuerier Jenkins 信息查询接口
type JenkinsInfoQuerier interface {
BusinessInfoQuerier
GetOrganizations(ctx context.Context) ([]string, error)
GetRepositories(ctx context.Context, org string) ([]string, error)
GetBranches(ctx context.Context, org, repo string) ([]string, error)
}
// ModulePermissionChecker 权限检查器接口（通用）
type ModulePermissionChecker interface {
CheckPermission(ctx context.Context, userID int64, userRole string,
resourceID, resourceType, permissionType string) (bool, error)
GetAccessibleResourceIDs(ctx context.Context, userID int64, userRole string,
resourceType string) ([]string, error)
}
```
### 8.4 项目权限（ProjectACL）
#### 8.4.1 设计原则
- 权限粒度：**模块级**（basic_info/business_info/environment_info/middleware_info/authorization_info）
- SuperAdmin 默认拥有所有权限，无需存储 ACL 记录
- 项目填写人自动获得非授权模块的 view 权限
#### 8.4.2 模块代码与 JSONB 映射
| 模块代码 | JSONB 字段 | 说明 |
|:---|:---|:---|
| `basic_info` | `projects.basic_info` | 省份、城市、联系人等 |
| `business_info` | `projects.deploy_business` | 部署人、版本、入口等 |
| `environment_info` | `projects.deploy_env` | 主机、网络、管理方式等 |
| `middleware_info` | `projects.deploy_middleware` | MySQL/Redis/EMQX 等 |
| `authorization_info` | `project_auth_configs.*` | TOTP 授权（仅 SuperAdmin） |
#### 8.4.3 权限检查规则
```go
// CheckProjectModulePermission 规则:
// 1. SuperAdmin 拥有所有权限
// 2. authorization_info 模块仅 SuperAdmin 可访问
// 3. 项目填写人自动拥有非授权模块的 view 权限
// 4. 其他用户查询 project_acls 表
```
---
## 9. 数据模型
### 9.1 核心表概览
| 表 | 作用 | 关键字段 |
|:---|:---|:---|
| `users` | 账户信息 | username, english_username, password_hash, role, status, registered_by_id, password_expires_at, account_expires_at, must_change_password, failed_login_attempts, locked_until |
| `rsa_keypairs` | RSA 密钥对 | public_key/ private_key (PEM), expires_at |
| `jenkins_acls` | Jenkins 层级权限 | user_id, organization_folder, repository_name?, branch_name?, permission_level, can_view, can_build, granted_by |
| `project_acls` | 项目模块级权限 | user_id, project_id, module_code, can_view, can_export, granted_by |
| `user_permission_caches` | 用户权限 L2 缓存 | user_id, permission_tree (JSON), updated_at |
| `system_configs` | 系统配置 | key, value, description |
### 9.2 用户表 DDL (users)
```go
// User 用户表
type User struct {
ID int64 `gorm:"primaryKey;autoIncrement" json:"id"`
Username string `gorm:"uniqueIndex;not null;size:50" json:"username"` // 中文真实姓名
EnglishUsername string `gorm:"size:100" json:"english_username"` // 英文用户名(昵称)
PasswordHash string `gorm:"not null;size:255" json:"-"` // 加密后的密码
AvatarID string `gorm:"size:50;default:'default_1'" json:"avatar_id"` // 头像ID
AvatarFrameID string `gorm:"size:50;default:'default'" json:"avatar_frame_id"` // 头像框ID
Gender string `gorm:"size:10;default:'male'" json:"gender"` // 性别: male/female
Email string `gorm:"uniqueIndex;size:100" json:"email"` // 邮箱
Phone string `gorm:"size:20" json:"phone"` // 手机号
ShortNumber string `gorm:"size:10" json:"short_number"` // 短号
WorkID string `gorm:"size:50" json:"work_id"` // 工号
GroupName string `gorm:"size:100" json:"group_name"` // 所属小组
Company string `gorm:"size:100" json:"company"` // 公司名称
DevRole string `gorm:"size:50;default:'unknown'" json:"dev_role"` // 开发角色
// 注册关系
RegisteredByID int64 `json:"registered_by_id"` // 注册人ID
RegisteredByName string `gorm:"size:64" json:"registered_by_name"` // 注册人姓名（冗余）
// 角色与状态
Role string `gorm:"not null;size:20;default:'normal'" json:"role"` // 系统角色
Status string `gorm:"not null;size:20;default:'disabled'" json:"status"` // 状态
// 密码策略
PasswordExpiresAt *time.Time `json:"password_expires_at"` // 密码过期时间
MustChangePassword bool `gorm:"default:true" json:"must_change_password"` // 是否需要强制改密
// 账户有效期（新增）
AccountExpiresAt *time.Time `json:"account_expires_at"` // 账户有效期
// 登录锁定
FailedLoginAttempts int `gorm:"default:0" json:"failed_login_attempts"`
LockedUntil *time.Time `json:"locked_until"`
// MFA
MFASecret string `gorm:"size:100" json:"-"`
// 审计字段
CreatedAt time.Time `gorm:"autoCreateTime" json:"created_at"`
UpdatedAt time.Time `gorm:"autoUpdateTime" json:"updated_at"`
DeletedAt *time.Time `gorm:"index" json:"deleted_at,omitempty"`
LastLoginAt *time.Time `json:"last_login_at"`
}
```
### 9.3 用户表新增字段说明
| 字段 | 类型 | 说明 | 默认值 |
|:---|:---|:---|:---|
| `registered_by_name` | varchar(64) | 注册人姓名（冗余存储，便于展示） | NULL |
| `must_change_password` | bool | 是否需要强制修改密码 | true |
| `account_expires_at` | datetime | 账户有效期，NULL表示永久有效 | NULL |
### 9.4 RSA 密钥表（rsa_keypairs）
- 存储 PEM 文本及过期时间；`RSAService` 负责加载、轮换、缓存与过期清理。
### 9.5 Jenkins 权限表（jenkins_acls）
- 层级列可空实现覆盖：org=不空，repo/branch 为空；repo 级：branch 空；branch 级：三列全填。
- `permission_level` 归档实际层级，便于查询。
- 详见 [8.2 Jenkins 层级权限](#82-jenkins-层级权限-jenkins_acls)。
### 9.6 项目权限表（project_acls）
- 模块级权限控制：user_id + project_id + module_code 组合唯一。
- 权限类型：can_view（查看）、can_export（导出）。
- 索引：`idx_project_acl_user`（用户维度）、`idx_project_acl_project`（项目+模块维度）。
- SuperAdmin 不存储记录，权限检查时直接放行。
---
## 10. 接口设计 (API)
### 10.1 认证
| 方法 | 路径 | 说明 | 鉴权 |
|:---|:---|:---|:---|
| GET | `/api/auth/rsa/public-key` | 获取 RSA 公钥 | 公共 |
| POST | `/api/auth/login` | RSA 加密密码登录，返回 JWT | 公共 |
| POST | `/api/auth/register` | 自助注册（创建 disabled 用户） | 公共 |
### 10.2 用户管理
| 方法 | 路径 | 说明 | 鉴权 |
|:---|:---|:---|:---|
| GET | `/api/users` | 列表，支持角色/状态/组/搜索/Scope | JWT |
| GET | `/api/users/:id` | 用户详情 + 权限 | JWT |
| POST | `/api/users` | 创建用户（自动创建注册工单） | JWT + Admin |
| PUT | `/api/users/:id` | 更新用户（仅用于保存草稿，正式修改需工单） | JWT + Admin |
| DELETE | `/api/users/:id` | 删除用户（仅SuperAdmin可直接删除） | JWT + SuperAdmin |
| PUT | `/api/user/profile` | 更新本人资料（头像/密码） | JWT |
| PUT | `/api/user/password` | 本人改密（校验旧密码） | JWT |
| PUT | `/api/user/password/force-change` | 首次登录强制改密 | JWT |
### 10.3 权限（Jenkins）
| 方法 | 路径 | 说明 | 鉴权 |
|:---|:---|:---|:---|
| GET | `/api/permissions/jenkins/my-tree/organizations` | 我的组织列表 | JWT |
| POST | `/api/permissions/jenkins/my-tree/repositories` | 我的仓库（按 org） | JWT |
| POST | `/api/permissions/jenkins/my-tree/branches` | 我的分支（按 org/repo） | JWT |
| GET | `/api/permissions/jenkins/my-tree/full` | 我的权限树（缓存/重建） | JWT |
| GET | `/api/permissions/jenkins/check/:organization/:branch` | 检查分支权限 | JWT |
| GET | `/api/permissions/jenkins/tree` | 全量权限树（Admin） | JWT + Admin |
| GET | `/api/permissions/jenkins/users/role/:role` | 按角色查用户 | JWT + Admin |
| GET | `/api/permissions/jenkins/:userId` | 获取用户 Jenkins 权限 | JWT + Admin |
| POST | `/api/permissions/jenkins/assign` | 分配权限（层级覆盖） | JWT + Admin |
| POST | `/api/permissions/jenkins/copy` | 拷贝权限 | JWT + Admin |
| GET | `/api/permissions/jenkins/user-tree/:userId/organizations` | 懒加载组织 | JWT + Admin |
| GET | `/api/permissions/jenkins/user-tree/:userId/organizations/:org/repositories` | 懒加载仓库 | JWT + Admin |
| GET | `/api/permissions/jenkins/user-tree/:userId/organizations/:org/repositories/:repo/branches` | 懒加载分支 | JWT + Admin |
### 10.4 项目权限接口
| 方法 | 路径 | 说明 | 鉴权 |
|:---|:---|:---|:---|
| GET | `/api/permissions/projects/user/:userId/summary` | 获取用户项目权限摘要 | JWT + Admin |
| POST | `/api/permissions/projects/grant` | 授予项目模块权限 | JWT + Admin |
| POST | `/api/permissions/projects/revoke` | 撤销项目模块权限 | JWT + Admin |
> **注意**：前端不允许直接调用创建工单接口，用户注册/管理工单通过用户管理接口（如 `POST /api/users`、`PUT /api/users/:id`）内部自动创建。
### 10.5 系统配置
| 方法 | 路径 | 说明 | 鉴权 |
|:---|:---|:---|:---|
| GET | `/api/user/system-config` | 获取配置（为空时返回默认值） | JWT |
| PUT | `/api/user/system-config` | 更新配置 | JWT |
---
## 11. 业务流程
### 11.1 登录流程
```mermaid
sequenceDiagram
participant FE as 前端
participant UA as rmdc-user-auth
FE->>UA: GET /api/auth/rsa/public-key
UA-->>FE: 公钥
FE->>UA: POST /api/auth/login (encrypted_password)
UA->>UA: RSA 解密 + bcrypt 校验
UA->>UA: 检查账户状态/有效期/密码过期
UA->>UA: 生成 JWT(4h)
UA-->>FE: token + userDTO + 附加标识
Note over FE,UA: 附加标识：<br/>must_change_password<br/>password_expire_days<br/>account_expire_days
alt must_change_password = true
FE->>FE: 跳转强制改密页面
FE->>UA: PUT /api/user/password/force-change
UA->>UA: 更新密码,重置过期时间
UA-->>FE: 改密成功
end
```
### 11.2 用户注册工单
```mermaid
sequenceDiagram
participant User as 已登录用户
participant UA as rmdc-user-auth
participant WP as rmdc-work-procedure
participant SA as SuperAdmin
User->>UA: POST /api/users (创建用户)
UA->>UA: 权限检查：可注册该角色？
UA->>UA: 创建用户(status=disabled, 默认密码)
UA->>UA: 设置 account_expires_at
UA->>UA: 设置 must_change_password = true
UA->>WP: CreateWorkflow(user_registration, pending_review)
WP-->>UA: workflow_id
UA-->>User: 返回成功
WP->>SA: 通知待审批
alt 审批通过
SA->>WP: approve
WP->>UA: ActivateUser
UA->>UA: status = active
else 打回
SA->>WP: return
WP->>User: 通知修改
User->>UA: PUT /api/users/:id
User->>WP: resubmit
else 撤销
User->>WP: revoke
WP->>UA: DeletePendingUser
UA->>UA: DELETE (status=disabled)
end
```
### 11.3 用户管理工单
> **重要**：前端不允许直接调用创建工单接口，工单由用户管理接口内部自动创建。
```mermaid
sequenceDiagram
participant Operator as 操作人
participant UA as rmdc-user-auth
participant WP as rmdc-work-procedure
participant SA as SuperAdmin
Operator->>UA: PUT /api/users/:id (修改用户)
Note right of Operator: 或 POST /api/users/:id/enable|disable|delete
UA->>UA: CheckManagementPermission
UA->>UA: 记录原始数据快照
UA->>WP: CreateWorkflow(user_management)
WP-->>UA: workflow_id
UA-->>Operator: 返回成功
WP->>SA: 通知待审批
alt 审批通过
SA->>WP: approve
WP->>UA: ExecuteUserManagement
UA->>UA: 执行操作(update/enable/disable/delete)
else 打回
SA->>WP: return
WP->>Operator: 通知修改后重新提交
end
```
---
## 12. 安全与合规
- **传输安全**：登录密码必须使用 RSA-OAEP(SHA-256, 2048) 加密；禁止明文密码传输。
- **存储安全**：密码使用 bcrypt；RSA 私钥仅存 DB，不下发前端；敏感字段不外露。
- **账户状态**：仅 active 用户可通过 JWT 校验；locked/disabled 一律拒绝。
- **密码策略**：
- 默认 3 个月过期；修改/创建均刷新过期时间
- 注册返回 disabled，需审批激活
- 首次登录或密码重置后强制修改密码
- **账户有效期**：非 SuperAdmin 创建的用户必须设置有效期，过期后无法登录
- **Token**：HS256，4h 过期；无刷新，需重登；超时后自动失效。
- **权限检查**：SuperAdmin 全通；Admin 只能管理/授权 normal/third；权限分配需校验授予者是否具备权限。
- **"谁注册谁管理"**：非 SuperAdmin 只能管理自己注册的用户
- **TODO**：登录失败次数与锁定策略尚未实现；Watchdog 权限检查待补全。
---
## 13. 相关文档
| 文档 | 说明 |
|:---|:---|
| [用户认证PRD](1-user-auth-PRD.md) | 产品需求文档 |
| [用户权限设计](权限设计部分/3-用户部分-权限设计.md) | 用户注册管理权限设计 |
| [项目管理DDS](../4-rmdc-project-management/2-rmdc-project-management-DDS.md) | 参考文档结构（项目工单流程） |
| [工单模块DDS](../7-rmdc-work-procedure/1-rmdc-work-procedure-DDS.md) | 工单流程设计 |