registry/docs/原型设计.md

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

1. 页面流程

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)

{
  "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

{
  "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 接口封装