user-system/README.md

# User Management System (UMS)

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

## 快速开始

### 前置依赖

- Go 1.21+
- Node.js 18+
- SQLite（默认，无需安装）

### 启动后端

```bash
# 复制环境配置
cp .env.example .env
# 编辑 .env 填入必要配置（JWT_SECRET, DEFAULT_ADMIN_PASSWORD 等）

# 启动服务
go run ./cmd/server
```

服务启动后访问 `http://localhost:8080/api/v1/auth/bootstrap` 初始化管理员账号。

### 启动前端

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

## 项目结构

```
.
├── cmd/server/          # 后端入口
├── internal/            # 后端代码
│   ├── api/handler/     # HTTP 处理器
│   ├── api/middleware/  # 中间件（认证、权限、限流）
│   ├── auth/            # 认证服务（JWT/SSO）
│   ├── repository/      # 数据访问层
│   ├── service/         # 业务逻辑层
│   └── domain/          # 领域模型
├── frontend/admin/      # 管理后台前端
├── configs/             # 配置文件
├── docs/                # 详细文档
└── data/                # SQLite 数据库目录
```

## 核心功能

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

## 环境变量

关键配置项（详见 `.env.example`）：

| 变量 | 说明 | 必填 |
|------|------|------|
| `JWT_SECRET` | JWT 签名密钥 | 是 |
| `DEFAULT_ADMIN_EMAIL` | 初始管理员邮箱 | 是 |
| `DEFAULT_ADMIN_PASSWORD` | 初始管理员密码 | 是 |
| `SMTP_*` | 邮件服务配置 | 是（邮件功能）|
| `SMS_*` | 短信服务配置 | 否 |

## API 文档

完整 API 规范：`docs/API.md`

认证流程：
```
1. POST /api/v1/auth/register     # 注册用户
2. POST /api/v1/auth/login        # 登录获取 Token
3. POST /api/v1/auth/refresh      # 刷新 Token
```

## 开发命令

```bash
# 构建
go build ./cmd/server

# 测试
go test ./internal/... -cover

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

# Docker 构建
docker build -t ums .
```

## 部署

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

## 测试覆盖率

```
api/handler     15.6%
api/middleware  21.5%
auth            28.1%
repository      47.2%
internal/middleware 65.4%
```

目标：80%+