# 新闻资讯模块设计方案 ## 1. 概述 ### 1.1 模块定位 新闻资讯模块是飞点健康 CMS 系统的核心内容管理模块，用于发布和管理企业新闻、行业资讯、产品动态等内容。该模块与顶级菜单"新闻动态"关联，提供完整的栏目管理和资讯发布功能。 ### 1.2 设计目标 - 支持双格式发布：Markdown + HTML 富文本 - 复用现有成熟代码（personal-blog） - 支持图片资源管理（可作为独立顶级模块） - 提供良好的编辑体验和预览功能 ### 1.3 功能范围 ``` ┌─────────────────────────────────────────────────────────────┐ │ 新闻资讯模块 │ ├─────────────────┬─────────────────┬─────────────────────────┤ │ 栏目管理 │ 资讯管理 │ 图片管理 │ ├─────────────────┼─────────────────┼─────────────────────────┤ │ • 创建栏目 │ • 创建资讯 │ • 上传图片 │ │ • 编辑栏目 │ • 编辑资讯 │ • 图片列表 │ │ • 删除栏目 │ • 删除资讯 │ • 插入到文章 │ │ • 栏目排序 │ • 发布/草稿 │ • 删除图片 │ │ │ • Markdown编辑 │ │ │ │ • HTML富文本 │ │ │ │ • 预览功能 │ │ └─────────────────┴─────────────────┴─────────────────────────┘ ``` --- ## 2. 数据库设计 ### 2.1 数据表关系图 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ news_categories│ │ news_posts │ │ images │ │ (栏目表) │◄────────│ (资讯表) │────────►│ (图片表) │ ├─────────────────┤ 1:N ├─────────────────┤ N:M ├─────────────────┤ │ id (PK) │ │ id (PK) │ │ id (PK) │ │ name │ │ title │ │ filename │ │ slug (UQ) │ │ slug (UQ) │ │ file_path │ │ description │ │ content │ │ thumb_path │ │ sort_order │ │ content_type │◄───────│ description │ │ is_enabled │ │ summary │ │ file_size │ │ created_at │ │ cover_image │◄───────│ width │ │ updated_at │ │ category_id(FK) │ │ height │ └─────────────────┘ │ is_published │ │ created_at │ │ is_draft │ └─────────────────┘ │ view_count │ │ created_at │ │ updated_at │ └─────────────────┘ │ │ 1:N ▼ ┌─────────────────┐ │ news_post_images│ │ (文章图片关联) │ ├─────────────────┤ │ post_id (FK) │ │ image_id (FK) │ └─────────────────┘ ``` ### 2.2 表结构定义 #### 2.2.1 news_categories - 栏目表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | INTEGER | PK, AI | 主键 | | name | VARCHAR(50) | NOT NULL | 栏目名称 | | slug | VARCHAR(50) | UNIQUE, NOT NULL | URL标识（如：company-news） | | description | VARCHAR(200) | NULL | 栏目描述 | | sort_order | INTEGER | DEFAULT 0 | 排序权重 | | is_enabled | BOOLEAN | DEFAULT 1 | 是否启用 | | created_at | DATETIME | DEFAULT NOW | 创建时间 | | updated_at | DATETIME | DEFAULT NOW | 更新时间 | ```sql CREATE TABLE news_categories ( id INTEGER PRIMARY KEY AUTOINCREMENT, name VARCHAR(50) NOT NULL, slug VARCHAR(50) UNIQUE NOT NULL, description VARCHAR(200), sort_order INTEGER DEFAULT 0, is_enabled BOOLEAN DEFAULT 1, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ); ``` #### 2.2.2 news_posts - 资讯表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | INTEGER | PK, AI | 主键 | | title | VARCHAR(200) | NOT NULL | 资讯标题 | | slug | VARCHAR(200) | UNIQUE, NOT NULL | URL友好的标识 | | content | TEXT | NOT NULL | 内容 | | content_type | VARCHAR(10) | DEFAULT 'markdown' | 内容类型：markdown/html | | summary | VARCHAR(500) | NULL | 摘要（自动生成或手动填写）| | cover_image | VARCHAR(500) | NULL | 封面图路径 | | category_id | INTEGER | FK -> news_categories | 栏目ID（必填）| | is_published | BOOLEAN | DEFAULT 0 | 是否发布 | | is_draft | BOOLEAN | DEFAULT 1 | 是否草稿 | | view_count | INTEGER | DEFAULT 0 | 浏览次数 | | created_at | DATETIME | DEFAULT NOW | 创建时间 | | updated_at | DATETIME | DEFAULT NOW | 更新时间 | ```sql CREATE TABLE news_posts ( id INTEGER PRIMARY KEY AUTOINCREMENT, title VARCHAR(200) NOT NULL, slug VARCHAR(200) UNIQUE NOT NULL, content TEXT NOT NULL, content_type VARCHAR(10) DEFAULT 'markdown', summary VARCHAR(500), cover_image VARCHAR(500), category_id INTEGER NOT NULL, is_published BOOLEAN DEFAULT 0, is_draft BOOLEAN DEFAULT 1, view_count INTEGER DEFAULT 0, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (category_id) REFERENCES news_categories(id) ON DELETE RESTRICT ); ``` #### 2.2.3 images - 图片表（复用/扩展） 复用 personal-blog 的图片表结构，但提升为系统级资源表： | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | INTEGER | PK, AI | 主键 | | filename | VARCHAR(255) | NOT NULL | 存储文件名 | | original_name | VARCHAR(255) | NULL | 原始文件名 | | file_path | VARCHAR(500) | NOT NULL | 文件路径 | | thumb_path | VARCHAR(500) | NULL | 缩略图路径 | | description | VARCHAR(500) | NULL | 图片描述 | | file_size | INTEGER | NULL | 文件大小（字节）| | width | INTEGER | NULL | 图片宽度 | | height | INTEGER | NULL | 图片高度 | | module | VARCHAR(20) | DEFAULT 'news' | 所属模块：news/product/page等 | | created_at | DATETIME | DEFAULT NOW | 创建时间 | ```sql CREATE TABLE images ( id INTEGER PRIMARY KEY AUTOINCREMENT, filename VARCHAR(255) NOT NULL, original_name VARCHAR(255), file_path VARCHAR(500) NOT NULL, thumb_path VARCHAR(500), description VARCHAR(500), file_size INTEGER, width INTEGER, height INTEGER, module VARCHAR(20) DEFAULT 'news', created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); ``` --- ## 3. 后端 API 设计 ### 3.1 路由结构 ``` /api/v1/ ├── /news/ │ ├── GET /categories # 获取栏目列表 │ ├── POST /categories # 创建栏目 │ ├── GET /categories/{id} # 获取栏目详情 │ ├── PUT /categories/{id} # 更新栏目 │ ├── DELETE /categories/{id} # 删除栏目 │ ├── GET /posts # 获取资讯列表（分页、筛选） │ ├── POST /posts # 创建资讯 │ ├── GET /posts/{id} # 获取资讯详情 │ ├── PUT /posts/{id} # 更新资讯 │ ├── DELETE /posts/{id} # 删除资讯 │ ├── POST /posts/{id}/publish # 发布资讯 │ ├── POST /posts/{id}/unpublish # 取消发布 │ └── GET /posts/slug/{slug} # 通过slug获取（访客端） └── /images/ ├── GET / # 获取图片列表（分页） ├── POST /upload # 上传图片 ├── DELETE /{id} # 删除图片 └── POST /{id}/insert # 获取图片插入URL ``` ### 3.2 核心 API 定义 #### 3.2.1 栏目管理 API **GET /api/v1/news/categories** ```json // Response { "items": [ { "id": 1, "name": "公司新闻", "slug": "company-news", "description": "飞点健康最新动态", "sort_order": 1, "is_enabled": true, "post_count": 15, "created_at": "2024-01-15T08:00:00" } ], "total": 5 } ``` **POST /api/v1/news/categories** ```json // Request { "name": "公司新闻", "slug": "company-news", "description": "飞点健康最新动态", "sort_order": 1 } ``` #### 3.2.2 资讯管理 API **GET /api/v1/news/posts?page=1&size=10&category_id=1&keyword=xxx** ```json // Response { "items": [ { "id": 1, "title": "飞点健康完成A轮融资", "slug": "feidian-series-a", "summary": "今日，飞点健康宣布完成数千万元A轮融资...", "cover_image": "/uploads/covers/xxx.jpg", "category": { "id": 1, "name": "公司新闻" }, "content_type": "markdown", "is_published": true, "is_draft": false, "view_count": 1250, "created_at": "2024-01-20T10:30:00", "updated_at": "2024-01-20T10:30:00" } ], "total": 50, "page": 1, "size": 10 } ``` **POST /api/v1/news/posts** ```json // Request { "title": "飞点健康完成A轮融资", "slug": "feidian-series-a", "content": "# 飞点健康完成A轮融资\n\n今日...", "content_type": "markdown", "summary": "今日，飞点健康宣布完成数千万元A轮融资...", "cover_image": "/uploads/covers/xxx.jpg", "category_id": 1, "is_draft": false } ``` --- ## 4. 前端设计 ### 4.1 页面结构 ``` /admin/news # 资讯管理首页（列表） /admin/news/posts # 资讯列表 /admin/news/posts/new # 新建资讯 /admin/news/posts/:id/edit # 编辑资讯 /admin/news/categories # 栏目管理 /admin/images # 图片管理（可作为顶级菜单） /news # 访客端新闻列表页 /news/:slug # 访客端新闻详情页 ``` ### 4.2 组件设计 #### 4.2.1 管理端组件 ``` src/pages/admin/news/ ├── NewsLayout.jsx # 新闻模块布局（侧边栏导航） ├── PostList.jsx # 资讯列表页 ├── PostEdit.jsx # 资讯编辑页（双编辑器支持） ├── CategoryList.jsx # 栏目列表页 └── components/ ├── MarkdownEditor.jsx # Markdown编辑器（复用blog） ├── HtmlEditor.jsx # HTML富文本编辑器 ├── PostForm.jsx # 资讯表单（标题、栏目、封面等） ├── CategoryForm.jsx # 栏目表单 ├── ImagePicker.jsx # 图片选择器 └── PostPreview.jsx # 文章预览组件 src/pages/admin/images/ ├── ImageManager.jsx # 图片管理页（可作为独立模块） └── components/ ├── ImageUploader.jsx # 图片上传组件 ├── ImageGrid.jsx # 图片网格展示 └── ImageDetail.jsx # 图片详情/编辑 ``` #### 4.2.2 编辑器选型 | 格式 | 编辑器 | 特点 | 图片支持 | |------|--------|------|----------| | Markdown | react-markdown-editor-lite | 轻量、性能好 | 支持粘贴/拖拽上传 | | HTML | TinyMCE 6 | 功能丰富、稳定 | 内置图片上传插件 | **TinyMCE 配置要点：** ```javascript { plugins: 'image link media table code fullscreen', toolbar: 'undo redo | formatselect | bold italic | alignleft aligncenter alignright | bullist numlist | image media link | table | code fullscreen', images_upload_url: '/api/v1/images/upload', images_upload_handler: customUploadHandler } ``` ### 4.3 路由配置 ```javascript // 添加到 AdminLayout 侧边栏 { path: '/admin/news', label: '新闻资讯', icon: Newspaper, children: [ { path: '/admin/news/posts', label: '资讯管理' }, { path: '/admin/news/categories', label: '栏目管理' } ] } // 独立图片管理（可作为顶级菜单） { path: '/admin/images', label: '图片管理', icon: Image } ``` --- ## 5. 复用代码清单 ### 5.1 从 personal-blog 复用 | 组件/模块 | 源文件路径 | 目标路径 | 修改点 | |-----------|-----------|----------|--------| | 图片模型 | backend/models.py Image | backend/app/models/image.py | 添加 module 字段 | | 图片上传API | backend/routers/images.py | backend/app/routers/images.py | 适配新路由前缀 | | 图片管理页 | frontend/src/pages/admin/Images.jsx | frontend/src/pages/admin/images/ImageManager.jsx | 样式统一 | | Markdown编辑器 | 无（需新增） | frontend/src/pages/admin/news/components/MarkdownEditor.jsx | - | ### 5.2 复用策略 1. **图片管理**：完全复用 blog 的图片表结构，添加 `module` 字段区分来源 2. **文件上传**：复用上传逻辑，统一存储到 `/uploads/news/` 3. **缩略图生成**：复用 PIL 缩略图生成逻辑 --- ## 6. 访客端展示 ### 6.1 新闻列表页 (/news) - 顶部显示栏目筛选标签 - 列表展示：封面图、标题、摘要、发布时间、浏览量 - 支持分页加载 ### 6.2 新闻详情页 (/news/:slug) - 文章标题、发布时间、栏目 - 根据 content_type 渲染不同格式 - Markdown: 使用 react-markdown + remark-gfm - HTML: 使用 dangerouslySetInnerHTML（需 XSS 过滤） ### 6.3 首页新闻模块联动 home_modules 表中 type=news 的模块，从 news_posts 表读取最新 N 条数据展示。 --- ## 7. 实现步骤 ### Phase 1: 数据库与后端 API（预计 2-3 天） 1. [ ] 创建数据库表（categories, posts, images） 2. [ ] 实现栏目管理 API 3. [ ] 实现资讯管理 API 4. [ ] 复用/改造图片上传 API 5. [ ] 编写 API 测试 ### Phase 2: 管理端前端（预计 3-4 天） 1. [ ] 创建新闻模块路由和布局 2. [ ] 实现栏目管理页面 3. [ ] 实现 Markdown 编辑器组件 4. [ ] 实现 HTML 编辑器组件（TinyMCE 集成） 5. [ ] 实现资讯列表页 6. [ ] 实现资讯编辑页（双编辑器切换） 7. [ ] 实现图片管理页面 ### Phase 3: 访客端与联调（预计 2 天） 1. [ ] 实现新闻列表页 2. [ ] 实现新闻详情页（支持 Markdown/HTML 渲染） 3. [ ] 联调首页新闻模块数据 4. [ ] 顶部菜单"新闻动态"链接配置 ### Phase 4: 优化与测试（预计 1-2 天） 1. [ ] 图片懒加载优化 2. [ ] XSS 防护（HTML 内容过滤） 3. [ ] 移动端适配 4. [ ] 性能测试 --- ## 8. 技术要点 ### 8.1 XSS 防护 对于 HTML 格式的内容，必须做 XSS 过滤： ```python # 后端存储前过滤（可选） from bleach import clean allowed_tags = ['p', 'br', 'strong', 'em', 'u', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'ul', 'ol', 'li', 'a', 'img', 'table', 'thead', 'tbody', 'tr', 'td', 'th'] allowed_attrs = {'a': ['href', 'title'], 'img': ['src', 'alt', 'width', 'height']} cleaned_html = clean(raw_html, tags=allowed_tags, attributes=allowed_attrs) ``` ### 8.2 图片存储规范 ``` uploads/ ├── news/ # 新闻资讯图片 │ ├── 2024/01/ # 按年月组织 │ │ ├── xxx.jpg │ │ └── thumbnails/ # 缩略图 │ └── ... ├── products/ # 产品图片 ├── pages/ # 页面图片 └── common/ # 通用图片 ``` ### 8.3 slug 生成规则 ```python def generate_slug(title: str) -> str: """将标题转换为 URL 友好的 slug""" # 1. 移除特殊字符 # 2. 空格替换为连字符 # 3. 转小写 # 4. 处理重复（添加数字后缀） ``` --- ## 9. 扩展性考虑 ### 9.1 未来可扩展功能 - [ ] 文章标签系统 - [ ] 文章评论功能 - [ ] 文章定时发布 - [ ] 文章版本历史 - [ ] 文章 SEO 元数据管理 - [ ] 多语言支持 ### 9.2 图片管理升级 当前作为新闻模块子功能，后续可提升为系统级资源中心，支持： - 图片分类/标签 - 批量上传 - 图片搜索 - 在线编辑（裁剪、滤镜） --- ## 10. 参考资源 ### 10.1 编辑器文档 - TinyMCE React: https://www.tiny.cloud/docs/tinymce/6/react-cloud/ - react-markdown-editor-lite: https://github.com/HarryChen0506/react-markdown-editor-lite ### 10.2 代码参考 - personal-blog Markdown 编辑实现 - personal-blog 图片管理实现 --- *文档版本: 1.0* *创建时间: 2026-04-20* *作者: nanobot*