test: add service layer unit tests for webhook/metadata/error/config

- webhook_service_test.go: isPrivateIP, isSafeURL, computeHMAC
- request_metadata_test.go: context functions
- classified_error_test.go: error types
- config_defaults_test.go: password reset/SMS defaults
- email_config_test.go: email code defaults
- auth_runtime_test.go: isUserNotFoundError

Service coverage: 11.2% -> 14.7%

README.md

@@ -1,2 +1,119 @@
-# user-system
+# 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%+