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/                # 详细文档
│   ├── code-review/     # Review 报告与修复记录
│   └── status/          # 项目状态文档
└── data/                # SQLite 数据库目录
```

## 项目状态

当前状态：**B / 有条件就绪** (2026-05-29)

- ✅ 后端构建: `go build ./cmd/server` PASS
- ✅ 后端测试: `go test ./...` PASS  
- ✅ 前端构建: `npm run build` PASS
- ✅ 前端测试: `npm run test:run` PASS (522 tests)
- ✅ 安全审计: `npm audit` 0 vulnerabilities
- ✅ P0 Blocker: 5/5 已修复
- ✅ P1 重要问题: 5/5 已修复
- ⚠️ P2 优化项: 进行中（覆盖率提升）

详见：[docs/status/REAL_PROJECT_STATUS.md](docs/status/REAL_PROJECT_STATUS.md)

## 核心功能

| 功能 | 说明 |
|------|------|
| 用户管理 | 注册、登录、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 vet ./...
go test ./... -count=1

# 前端最低验证矩阵（显式移除 NODE_ENV=production 干扰）
cd frontend/admin && env -u NODE_ENV npm run lint
cd frontend/admin && env -u NODE_ENV npm run build
cd frontend/admin && env -u NODE_ENV npm run test:run
```

## 部署

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

## 测试状态（2026-05-29 live snapshot）

| 测试类型 | 状态 |
|----------|------|
| Go 构建 | ✅ 通过 |
| Go vet | ✅ 通过 |
| Go 测试 | ✅ 通过（`go test ./... -count=1`） |
| 前端 lint | ✅ 通过 |
| 前端构建 | ✅ 通过 |
| 前端测试 | ✅ 通过（82 files / 522 tests） |
| 依赖审计 | ✅ 通过（prod/dev 均 0 漏洞） |
| 浏览器级 E2E | ✅ 通过（Playwright CDP full-chain） |

## 项目状态

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

**2026-05-29 最新状态：**
- 后端 build / vet / full test matrix 全绿
- 前端 lint / build / unit test 全绿
- 前端 dev toolchain 审计收敛为 0 漏洞
- 浏览器级真实 E2E 已闭环
- 全部 P0/P1 review blocker 已修复
- 当前项目评级：B / 有条件就绪

**边界说明：** 当前可以诚实宣称的是“本地可审计的后端/前端验证与浏览器级真实 E2E 已闭环”；不应夸大为“所有生产外部集成和完整上线材料都已全部闭环”。