# 页面实现文档：登录 / 项目列表 / 系统管理

## 1. 页面流程

```mermaid
flowchart TD
    A[登录页 login.html] -->|登录成功| B[项目列表页 projects.html]
    B -->|点击项目卡片| D[配置管理页 index.html]
    B -->|管理员点击「系统管理」| C[系统管理 admin.html]
    C -->|返回项目列表| B
    A -.->|未登录访问任意页面| B
    B -.->|token 过期 API 返回 401| A
```

## 2. 认证机制

- 登录成功返回 `{ token, user }`，前端存入 `localStorage`。
- 所有 API 请求自动携带 `Authorization: Bearer <token>` 头。
- 服务端使用内存 session（`src/routes/auth.js`），TTL 24 小时。
- API 返回 401 时前端自动清理凭证并跳转登录页。
- **首次启动自动创建默认管理员**：`admin / admin123`（密码经 scrypt 加盐哈希，存于 `data/users.json`）。

| 角色 | 项目列表 | 进入配置 | 系统管理 |
|------|---------|---------|---------|
| 管理员 (admin) | ✓ | ✓ | ✓ |
| 普通用户 (user) | ✓ | ✓ | ✗（入口隐藏 + 后端 403） |

## 3. 页面清单（public/ 目录）

| 文件 | 说明 |
|------|------|
| `public/login.html` | 登录页，居中卡片，深蓝渐变背景 |
| `public/projects.html` | 项目列表页，卡片网格 + 搜索 + 新建/删除项目 |
| `public/admin.html` | 系统管理页，用户管理 + Token 管理两个 Tab |
| `public/index.html` | 配置管理页（原有），标题栏增加用户信息/系统管理/退出入口 |

## 4. 新增 API

### 4.1 认证

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/login` | 登录，Body: `{ username, password }`，返回 `{ token, user }` |
| POST | `/api/auth/logout` | 注销，销毁 session |
| GET  | `/api/auth/me` | 获取当前登录用户 |

### 4.2 用户管理（需管理员）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET    | `/api/users` | 用户列表（不含密码字段） |
| POST   | `/api/users` | 新增用户 `{ username, displayName, password, role, enabled }` |
| PUT    | `/api/users/:id` | 编辑 `{ displayName, role, enabled }` |
| PUT    | `/api/users/:id/password` | 重置密码 `{ password }` |
| DELETE | `/api/users/:id` | 删除用户 |

### 4.3 Token 管理（需管理员）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET    | `/api/tokens` | Token 列表 |
| POST   | `/api/tokens` | 生成 `{ name, projectId, permission, expiresInDays }`，返回含明文 value |
| PUT    | `/api/tokens/:id` | 编辑 `{ name, projectId, permission, enabled }` |
| PUT    | `/api/tokens/:id/revoke` | 吊销 |
| DELETE | `/api/tokens/:id` | 删除 |

## 5. 数据模型

`data/` 目录扩展：

```
data/
├── users.json       # 用户表（password 为 salt:hash）
└── api-tokens.json  # API Token 表（reg_ 前缀，MCP token 仍由 mcp.json 管理）
```

### 用户 (User)

```json
{
  "id": "a1b2c3d4",
  "username": "admin",
  "displayName": "系统管理员",
  "password": "salt:scrypt-hash",
  "role": "admin",
  "enabled": true,
  "createdAt": "2026-09-11T08:00:00.000Z",
  "updatedAt": "2026-09-11T08:00:00.000Z",
  "lastLoginAt": "2026-09-11T09:00:00.000Z"
}
```

### API Token

```json
{
  "id": "x1y2z3a4",
  "name": "CI 自动发布",
  "projectId": "proj-001",
  "permission": "readwrite",
  "value": "reg_<hex>",
  "enabled": true,
  "createdAt": "2026-09-11T08:00:00.000Z",
  "expiresAt": "2026-12-10T08:00:00.000Z"
}
```

## 6. 目录结构变更

```
src/
├── server.js              # 挂载 auth/users/tokens 路由 + 全局认证中间件
├── routes/
│   ├── auth.js            # 登录/登出/me + session 管理
│   ├── users.js           # 用户管理（管理员）
│   └── tokens.js          # Token 管理（管理员）
└── services/
    ├── userService.js     # 用户业务逻辑 + scrypt 密码哈希
    └── tokenService.js    # Token 业务逻辑

public/
├── login.html             # 登录页
├── projects.html          # 项目列表页
├── admin.html             # 系统管理页
└── js/api.js              # 新增 auth/user/token 接口封装
```