You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
11 KiB
11 KiB
Admin后台管理系统设计文档
概述
为 koa3-demo 项目设计并实现一个完整的后台管理系统，允许注册用户管理自己的文章并查看联系我们的提交信息。系统采用传统的左侧导航栏布局，不继承现有页面样式，完全独立实现。
核心需求
- 注册用户可以对自己的文章进行增删改查操作
- 展示联系表单提交的信息
- 采用Session认证，不使用API接口
- 独立的管理界面，左侧导航栏+右侧内容区域
- 不允许修改其他现有代码
架构设计
整体架构图
graph TB
A[用户访问 /admin] --> B[AdminController]
B --> C{Session验证}
C -->|未登录| D[跳转登录页]
C -->|已登录| E[后台主界面]
E --> F[文章管理模块]
E --> G[联系信息模块]
F --> H[ArticleService]
G --> I[ContactService]
H --> J[ArticleModel]
I --> K[ContactModel]
J --> L[(Articles表)]
K --> M[(Contacts表)]
模块架构
classDiagram
class AdminController {
+dashboard()
+articlesIndex()
+articleShow()
+articleCreate()
+articleEdit()
+articleUpdate()
+articleDelete()
+contactsIndex()
+contactShow()
+contactDelete()
}
class ContactModel {
+findAll()
+findById()
+create()
+delete()
+findByDateRange()
}
class ContactService {
+getAllContacts()
+getContactById()
+deleteContact()
+getContactsByDateRange()
}
AdminController --> ContactService
AdminController --> ArticleService
ContactService --> ContactModel
ArticleService --> ArticleModel
数据模型设计
联系信息表 (contacts)
| 字段名 | 类型 | 约束 | 描述 |
|---|---|---|---|
| id | INTEGER | PRIMARY KEY | 主键ID |
| name | VARCHAR(100) | NOT NULL | 联系人姓名 |
| VARCHAR(255) | NOT NULL | 邮箱地址 | |
| subject | VARCHAR(255) | NOT NULL | 主题 |
| message | TEXT | NOT NULL | 留言内容 |
| ip_address | VARCHAR(45) | NULL | IP地址 |
| user_agent | TEXT | NULL | 浏览器信息 |
| status | ENUM('unread','read','replied') | DEFAULT 'unread' | 处理状态 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 |
数据库迁移设计
-- 创建联系信息表
CREATE TABLE contacts (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name VARCHAR(100) NOT NULL,
email VARCHAR(255) NOT NULL,
subject VARCHAR(255) NOT NULL,
message TEXT NOT NULL,
ip_address VARCHAR(45),
user_agent TEXT,
status VARCHAR(20) DEFAULT 'unread',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- 创建索引
CREATE INDEX idx_contacts_status ON contacts(status);
CREATE INDEX idx_contacts_created_at ON contacts(created_at);
CREATE INDEX idx_contacts_email ON contacts(email);
后台界面设计
布局结构
┌─────────────────────────────────────────────────────┐
│ 顶部导航栏 │
├──────────────┬──────────────────────────────────────┤
│ │ │
│ 左侧导航 │ 主内容区域 │
│ │ │
│ - 仪表盘 │ ┌────────────────────────────────┐ │
│ - 文章管理 │ │ │ │
│ - 所有文章 │ │ 页面内容 │ │
│ - 新建文章 │ │ │ │
│ - 联系信息 │ │ │ │
│ │ └────────────────────────────────┘ │
│ │ │
└──────────────┴──────────────────────────────────────┘
页面流程图
flowchart TD
A[访问 /admin] --> B{用户已登录?}
B -->|否| C[跳转到登录页]
B -->|是| D[后台仪表盘]
D --> E[文章管理]
D --> F[联系信息管理]
E --> G[文章列表]
E --> H[新建文章]
G --> I[编辑文章]
G --> J[删除文章]
F --> K[联系信息列表]
K --> L[查看详情]
K --> M[删除信息]
C --> N[登录成功] --> D
核心功能模块
1. 文章管理模块
功能列表
- 文章列表: 显示当前用户的所有文章，支持状态筛选（草稿/已发布）
- 新建文章: 创建新文章，支持Markdown编辑
- 编辑文章: 修改现有文章内容
- 删除文章: 删除指定文章
- 发布/取消发布: 切换文章发布状态
权限控制
- 用户只能操作自己创建的文章
- 通过
author字段进行权限过滤
数据流程
sequenceDiagram
participant U as 用户
participant AC as AdminController
participant AS as ArticleService
participant AM as ArticleModel
participant DB as 数据库
U->>AC: 访问文章列表
AC->>AS: getUserArticles(userId)
AS->>AM: findByAuthor(userId)
AM->>DB: SELECT * FROM articles WHERE author = userId
DB-->>AM: 返回文章列表
AM-->>AS: 文章数据
AS-->>AC: 处理后的文章列表
AC-->>U: 渲染文章管理页面
2. 联系信息管理模块
功能列表
- 信息列表: 显示所有联系表单提交的信息
- 查看详情: 查看完整的联系信息内容
- 状态管理: 标记为已读/未读/已回复
- 删除信息: 删除不需要的联系信息
- 搜索筛选: 按时间、状态、邮箱等条件筛选
数据流程
sequenceDiagram
participant U as 用户
participant AC as AdminController
participant CS as ContactService
participant CM as ContactModel
participant DB as 数据库
U->>AC: 访问联系信息列表
AC->>CS: getAllContacts()
CS->>CM: findAll()
CM->>DB: SELECT * FROM contacts ORDER BY created_at DESC
DB-->>CM: 返回联系信息列表
CM-->>CS: 联系信息数据
CS-->>AC: 处理后的信息列表
AC-->>U: 渲染联系信息页面
技术实现规范
1. 控制器层设计
AdminController.js - 后台管理主控制器
- 继承现有项目架构模式
- 使用session进行用户认证
- 所有路由需要登录权限
2. 服务层设计
ContactService.js - 联系信息业务逻辑
- 提供联系信息的CRUD操作
- 实现状态管理功能
- 支持分页和搜索
3. 数据访问层设计
ContactModel.js - 联系信息数据模型
- 实现基础CRUD操作
- 支持条件查询和排序
- 与现有模型保持一致的设计模式
4. 视图层设计
布局文件: admin.pug - 后台专用布局
- 独立的CSS样式，不继承现有页面
- 响应式左侧导航栏设计
- 现代化的管理界面风格
页面模板:
admin/dashboard.pug- 仪表盘首页admin/articles/index.pug- 文章列表页admin/articles/create.pug- 新建文章页admin/articles/edit.pug- 编辑文章页admin/contacts/index.pug- 联系信息列表页admin/contacts/show.pug- 联系信息详情页
5. 路由设计
/admin GET - 后台首页（仪表盘）
/admin/articles GET - 文章列表
/admin/articles/create GET - 新建文章页面
/admin/articles POST - 创建文章
/admin/articles/:id GET - 查看文章详情
/admin/articles/:id/edit GET - 编辑文章页面
/admin/articles/:id PUT - 更新文章
/admin/articles/:id DELETE - 删除文章
/admin/contacts GET - 联系信息列表
/admin/contacts/:id GET - 联系信息详情
/admin/contacts/:id DELETE - 删除联系信息
/admin/contacts/:id/status PUT - 更新联系信息状态
安全考虑
1. 权限控制
- 所有后台路由需要用户登录
- 文章操作权限验证：用户只能操作自己的文章
- 联系信息管理：所有登录用户都可查看
2. 数据验证
- 服务端表单验证
- XSS防护：模板自动转义
- CSRF保护：利用现有session机制
3. 操作日志
- 记录重要操作（删除文章、删除联系信息）
- 利用现有logger系统
集成方案
1. 现有系统集成
- 联系表单增强: 修改BasePageController中的contactPost方法，将数据存储到数据库
- 用户认证复用: 利用现有session认证机制
- 数据库集成: 使用现有Knex.js配置和迁移系统
2. 不影响现有功能
- 新增模块独立部署在
/admin路径下 - 不修改现有控制器、服务和模型
- 独立的样式文件，避免样式冲突
文件结构
src/
├── controllers/
│ └── Page/
│ └── AdminController.js # 后台管理控制器
├── services/
│ └── ContactService.js # 联系信息服务
├── db/
│ ├── models/
│ │ └── ContactModel.js # 联系信息模型
│ └── migrations/
│ └── xxxx_create_contacts_table.mjs # 联系表迁移文件
├── views/
│ ├── layouts/
│ │ └── admin.pug # 后台布局模板
│ └── admin/
│ ├── dashboard.pug # 仪表盘
│ ├── articles/
│ │ ├── index.pug # 文章列表
│ │ ├── create.pug # 新建文章
│ │ └── edit.pug # 编辑文章
│ └── contacts/
│ ├── index.pug # 联系信息列表
│ └── show.pug # 联系信息详情
└── public/
├── css/
│ └── admin.css # 后台专用样式
└── js/
└── admin.js # 后台专用脚本
测试策略
单元测试
- ContactModel CRUD操作测试
- ContactService业务逻辑测试
- AdminController路由处理测试
集成测试
- 用户权限验证测试
- 文章管理完整流程测试
- 联系信息管理流程测试
安全测试
- 权限绕过测试
- XSS攻击防护测试
- 数据验证测试