user-system/README.md

# User Management System (UMS)

企业级用户管理系统，支持 RBAC 角色权限管理、多因素认证、设备信任和安全审计。

## 快速开始

### 安装 UMS CLI

```bash
# 下载对应平台的二进制文件
# Linux/macOS
curl -L -o ums https://github.com/user-management-system/ums/releases/latest/download/ums-linux-amd64
chmod +x ums

# Windows
curl -L -o ums.exe https://github.com/user-management-system/ums/releases/latest/download/ums-windows-amd64.exe

# 或使用 Go 安装
go install github.com/user-management-system/cmd/ums@latest
```

### 初始化系统

```bash
# 交互式初始化（推荐）
ums init

# 非交互式初始化
ums init \
  --admin-user admin \
  --admin-pass MySecretPassword123 \
  --admin-email admin@example.com \
  --cors-origin http://localhost:3000
```

初始化命令会：
1. 生成安全的 JWT 密钥
2. 创建配置文件 `config.yaml` 和 `.env`
3. 创建数据库目录并执行迁移
4. 初始化默认角色、权限和管理员账号

### 启动服务

```bash
ums serve
```

服务启动后访问 `http://localhost:8080/health` 确认服务正常运行。

### 前端

```bash
cd frontend/admin
npm install
npm run dev
```

## 项目结构

```
.
├── cmd/
│   ├── ums/              # UMS CLI 入口
│   │   └── cmd/          # CLI 子命令
│   │       ├── init.go   # 初始化命令
│   │       ├── serve.go  # 服务启动命令
│   │       └── version.go # 版本命令
│   └── server/           # 后端服务入口
├── internal/            # 后端代码
│   ├── api/handler/     # HTTP 处理器
│   ├── api/middleware/  # 中间件（认证、权限、限流）
│   ├── auth/            # 认证服务（JWT/SSO）
│   ├── repository/      # 数据访问层
│   ├── service/         # 业务逻辑层
│   ├── server/         # 服务器核心逻辑
│   └── domain/          # 领域模型
├── frontend/admin/      # 管理后台前端
├── configs/             # 配置文件
├── docs/                # 详细文档
└── data/                # SQLite 数据库目录
```

## 核心功能

| 功能 | 说明 |
|------|------|
| 用户管理 | 注册、登录、CRUD、批量操作 |
| RBAC | 角色继承、权限细粒度控制 |
| TOTP | Google Authenticator 二次验证 |
| 设备信任 | 信任设备免二次验证 |
| 登录日志 | 完整操作审计 |
| Webhook | 事件通知（user.created/deleted 等）|
| SSO | CAS 协议支持 |

## 安全特性

| 安全修复 | 状态 |
|----------|------|
| LIKE 查询 SQL 注入防护 | ✅ 已修复 |
| 登录失败计数器原子操作 | ✅ 已修复 |
| Refresh Token 黑名单 fail-closed | ✅ 已修复 |
| 验证码 Replay 防护 | ✅ 已修复 |
| CORS 危险配置检测 | ✅ 已修复 |
| UpdateUser IDOR 授权检查 | ✅ 已修复 |
| Login TOTP 设备信任门禁 | ✅ 已修复 |
| 游标分页排序一致性 | ✅ 已修复 |
| 错误信息泄露防护 | ✅ 已修复 |
| OAuth context 正确传播 | ✅ 已修复 |
| 密码修改后 Token 失效（PCE） | ✅ 已修复 |

## CLI 命令

```bash
ums init          # 初始化系统（交互式或非交互式）
ums serve         # 启动服务器
ums version       # 显示版本信息

# ums serve 选项
ums serve --port 8080           # 指定端口
ums serve --config ./prod.yaml  # 指定配置文件

# ums init 选项
ums init --db-type sqlite                # 数据库类型
ums init --db-path ./data/ums.db         # 数据库路径
ums init --redis-enable                  # 启用 Redis
ums init --redis-host localhost          # Redis 地址
ums init --admin-user admin             # 管理员用户名
ums init --admin-pass MyPassword123      # 管理员密码
ums init --admin-email admin@example.com # 管理员邮箱
ums init --port 8080                    # 服务端口
ums init --cors-origin http://example.com # CORS 域名
ums init --yes                          # 跳过确认
```

## 配置文件

初始化后生成以下配置文件：

**config.yaml** - 主配置文件
```yaml
server:
  port: 8080
  mode: release
database:
  type: sqlite
  dbname: "./data/user_management.db"
jwt:
  secret: "<自动生成的密钥>"
redis:
  enabled: false
```

**.env** - 环境变量（包含敏感信息，请勿提交）
```bash
JWT_SECRET=<自动生成的密钥>
BOOTSTRAP_SECRET=<自动生成的密钥>
DEFAULT_ADMIN_EMAIL=admin@example.com
DEFAULT_ADMIN_PASSWORD=<您设置的密码>
```

## 开发命令

```bash
# 构建 CLI
make build-cli

# 构建所有平台 CLI
make build-cli-all

# 构建服务器
go build ./cmd/server

# 测试
go test ./internal/... -skip TestScale -count=1

# 前端构建
cd frontend/admin && npm run build
```

## 部署

- 开发部署：`docs/DEPLOYMENT.md`
- 生产部署：`DEPLOY_GUIDE.md`
- 运行手册：`docs/guides/` 目录下的 7 个 Runbook

## 测试状态

| 测试类型 | 状态 |
|----------|------|
| Go 构建 | ✅ 通过 |
| Go vet | ✅ 通过 |
| Go 测试 | ✅ 通过（37个包） |
| 前端 lint | ✅ 通过 |
| 前端测试 | ✅ 通过（518个） |
| 集成测试 | ✅ 通过 |
| E2E 测试 | ✅ 通过 |

## 项目状态

完整项目状态：`docs/status/REAL_PROJECT_STATUS.md`

**2026-04-19 最新状态：** CLI 打包和系统初始化优化已完成，支持单一二进制文件部署和交互式/非交互式初始化。