# Admin后台管理系统设计文档 ## 概述 为 koa3-demo 项目设计并实现一个完整的后台管理系统，允许注册用户管理自己的文章并查看联系我们的提交信息。系统采用传统的左侧导航栏布局，不继承现有页面样式，完全独立实现。 ### 核心需求 - 注册用户可以对自己的文章进行增删改查操作 - 展示联系表单提交的信息 - 采用Session认证，不使用API接口 - 独立的管理界面，左侧导航栏+右侧内容区域 - 不允许修改其他现有代码 ## 架构设计 ### 整体架构图 ```mermaid 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表)] ``` ### 模块架构 ```mermaid 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 | 联系人姓名 | | email | 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 | 更新时间 | ### 数据库迁移设计 ```sql -- 创建联系信息表 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); ``` ## 后台界面设计 ### 布局结构 ``` ┌─────────────────────────────────────────────────────┐ │ 顶部导航栏 │ ├──────────────┬──────────────────────────────────────┤ │ │ │ │ 左侧导航 │ 主内容区域 │ │ │ │ │ - 仪表盘 │ ┌────────────────────────────────┐ │ │ - 文章管理 │ │ │ │ │ - 所有文章 │ │ 页面内容 │ │ │ - 新建文章 │ │ │ │ │ - 联系信息 │ │ │ │ │ │ └────────────────────────────────┘ │ │ │ │ └──────────────┴──────────────────────────────────────┘ ``` ### 页面流程图 ```mermaid 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` 字段进行权限过滤 #### 数据流程 ```mermaid 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. 联系信息管理模块 #### 功能列表 - **信息列表**: 显示所有联系表单提交的信息 - **查看详情**: 查看完整的联系信息内容 - **状态管理**: 标记为已读/未读/已回复 - **删除信息**: 删除不需要的联系信息 - **搜索筛选**: 按时间、状态、邮箱等条件筛选 #### 数据流程 ```mermaid 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攻击防护测试 - 数据验证测试