refc: Refactor project structure

2025-12-30 11:00:46 +08:00
parent 369655a9ea
commit 782a4e7795
106 changed files with 947 additions and 4184 deletions
@@ -0,0 +1,361 @@
+# 用户角色菜单管理系统
+
+基于 v-hono 框架的用户认证和权限管理系统，提供完整的用户角色管理和动态菜单功能。
+
+## 功能特性
+
+### 🔐 用户认证
+- 用户注册和登录
+- JWT 令牌认证
+- 密码加密存储
+- 会话管理
+
+### 👥 角色管理
+- 多级角色系统（admin、manager、user、guest）
+- 基于角色的权限控制
+- 灵活的权限分配
+
+### 📋 菜单管理
+- 动态菜单系统
+- 树形菜单结构
+- 基于权限的菜单显示
+- 菜单排序和图标支持
+
+### 🛡️ 安全特性
+- 密码 SHA256 加密
+- 令牌过期机制
+- 中间件权限验证
+- 防止路径遍历攻击
+
+## 系统架构
+
+```
+v-hono/
+├── hono/
+│   ├── auth.v              # 认证核心模块
+│   ├── auth_routes.v       # 认证路由
+│   ├── database.v          # 数据库管理
+│   ├── request.v           # 请求处理
+│   └── app.v              # 应用框架
+├── auth_example.v          # 完整示例
+└── README_AUTH_SYSTEM.md   # 本文档
+```
+
+## 快速开始
+
+### 1. 编译和运行
+
+```bash
+# 编译示例应用
+v auth_example.v
+
+# 运行应用
+./auth_example
+```
+
+### 2. 访问系统
+
+打开浏览器访问：`http://localhost:3000`
+
+### 3. 默认用户
+
+系统预创建了以下示例用户：
+
+| 用户名 | 密码 | 角色 | 权限 |
+|--------|------|------|------|
+| admin | admin123 | admin | 所有权限 |
+| manager | manager123 | manager | 读写管理权限 |
+| user | user123 | user | 读写权限 |
+| guest | guest123 | guest | 只读权限 |
+
+## API 接口
+
+### 认证接口
+
+#### 用户注册
+```http
+POST /api/auth/register
+Content-Type: application/json
+
+{
+  "username": "newuser",
+  "email": "user@example.com",
+  "password": "password123",
+  "role": "user"
+}
+```
+
+#### 用户登录
+```http
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "username": "admin",
+  "password": "admin123"
+}
+```
+
+响应：
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "expires_at": 1640995200
+}
+```
+
+#### 获取用户信息
+```http
+GET /api/auth/profile
+Authorization: <token>
+```
+
+#### 用户注销
+```http
+POST /api/auth/logout
+Authorization: <token>
+```
+
+### 菜单接口
+
+#### 获取用户菜单
+```http
+GET /api/auth/menus
+Authorization: <token>
+```
+
+#### 获取所有菜单（管理员）
+```http
+GET /api/auth/menus/all
+Authorization: <token>
+```
+
+#### 创建菜单项（管理员）
+```http
+POST /api/auth/menus
+Authorization: <token>
+Content-Type: application/json
+
+{
+  "name": "新菜单",
+  "path": "/new-menu",
+  "icon": "📄",
+  "parent_id": 0,
+  "sort_order": 1,
+  "permissions": ["read", "write"]
+}
+```
+
+### 受保护的路由
+
+#### 用户路由
+```http
+GET /api/protected/user
+Authorization: <token>
+```
+
+#### 管理员路由
+```http
+GET /api/protected/admin
+Authorization: <token>
+```
+
+## 角色权限说明
+
+### Admin（超级管理员）
+- 拥有所有权限
+- 可以管理所有用户和菜单
+- 可以访问所有系统功能
+
+### Manager（管理员）
+- 拥有读写和管理权限
+- 可以管理用户和菜单
+- 可以访问大部分系统功能
+
+### User（普通用户）
+- 拥有读写权限
+- 可以查看和编辑内容
+- 无法管理系统设置
+
+### Guest（访客）
+- 只有只读权限
+- 只能查看公开内容
+- 无法进行任何修改操作
+
+## 菜单权限配置
+
+菜单项通过 `permissions` 字段控制访问权限：
+
+```json
+{
+  "name": "用户管理",
+  "path": "/users",
+  "icon": "👥",
+  "permissions": ["read", "write", "manage"]
+}
+```
+
+权限说明：
+- `read`: 只读权限
+- `write`: 读写权限
+- `manage`: 管理权限
+- `*`: 所有权限（仅管理员）
+
+## 中间件使用
+
+### 认证中间件
+```v
+// 添加认证中间件
+app.use(hono.auth_middleware(auth_manager))
+```
+
+### 权限中间件
+```v
+// 添加权限检查中间件
+app.use(hono.permission_middleware('manage'))
+```
+
+## 数据库结构
+
+### users 表
+```sql
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    username TEXT UNIQUE NOT NULL,
+    email TEXT UNIQUE NOT NULL,
+    password_hash TEXT NOT NULL,
+    role TEXT NOT NULL,
+    status BOOLEAN DEFAULT 1,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+);
+```
+
+### menu_items 表
+```sql
+CREATE TABLE menu_items (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    path TEXT NOT NULL,
+    icon TEXT,
+    parent_id INTEGER DEFAULT 0,
+    sort_order INTEGER DEFAULT 0,
+    permissions TEXT,
+    status BOOLEAN DEFAULT 1,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+);
+```
+
+### user_sessions 表
+```sql
+CREATE TABLE user_sessions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    token TEXT UNIQUE NOT NULL,
+    expires_at INTEGER NOT NULL,
+    created_at INTEGER NOT NULL,
+    FOREIGN KEY (user_id) REFERENCES users (id)
+);
+```
+
+## 开发指南
+
+### 添加新的认证功能
+
+1. 在 `auth.v` 中添加新的方法
+2. 在 `auth_routes.v` 中添加对应的路由
+3. 更新前端界面
+
+### 自定义权限
+
+1. 修改 `UserRole` 枚举
+2. 更新 `check_permission` 方法
+3. 调整菜单权限配置
+
+### 扩展菜单功能
+
+1. 添加菜单编辑和删除接口
+2. 实现菜单拖拽排序
+3. 添加菜单缓存机制
+
+## 安全建议
+
+1. **密码安全**
+   - 使用强密码策略
+   - 定期更换密码
+   - 启用密码复杂度检查
+
+2. **令牌安全**
+   - 设置合理的过期时间
+   - 实现令牌刷新机制
+   - 支持令牌撤销
+
+3. **权限控制**
+   - 最小权限原则
+   - 定期审查权限
+   - 记录权限变更日志
+
+4. **数据安全**
+   - 数据库加密
+   - 定期备份
+   - 访问日志记录
+
+## 故障排除
+
+### 常见问题
+
+1. **数据库连接失败**
+   - 检查数据库文件权限
+   - 确保 SQLite 支持
+   - 验证数据库路径
+
+2. **认证失败**
+   - 检查用户名密码
+   - 验证令牌格式
+   - 确认令牌未过期
+
+3. **权限不足**
+   - 检查用户角色
+   - 验证菜单权限配置
+   - 确认中间件配置
+
+### 调试模式
+
+启用调试输出：
+```v
+// 在代码中添加调试信息
+println('Debug: $debug_info')
+```
+
+## 性能优化
+
+1. **数据库优化**
+   - 添加适当的索引
+   - 使用连接池
+   - 优化查询语句
+
+2. **缓存策略**
+   - 菜单缓存
+   - 用户信息缓存
+   - 权限缓存
+
+3. **并发处理**
+   - 使用连接池
+   - 实现请求队列
+   - 优化锁机制
+
+## 贡献指南
+
+1. Fork 项目
+2. 创建功能分支
+3. 提交更改
+4. 创建 Pull Request
+
+## 许可证
+
+MIT License
+
+## 联系方式
+
+如有问题或建议，请提交 Issue 或联系开发团队。