full/module/base/cms/README.md

# CMS Content Management System

一个高性能、可扩展的内容管理系统微服务，基于 gRPC 和 HTTP Gateway 架构，提供文章管理、页面管理、分类管理、标签管理等核心内容管理功能。

## 🚀 特性

- **📝 文章管理**: 完整的文章创建、编辑、删除、查询功能
- **📄 页面管理**: 静态页面和动态页面管理
- **🏷️ 分类管理**: 支持层级分类结构，灵活的内容组织
- **🔖 标签管理**: 多标签系统，便于内容分类和检索
- **💬 评论系统**: 完整的评论功能，支持嵌套评论
- **👍 互动功能**: 点赞、踩赞、评论计数等社交功能
- **📎 附件管理**: 文件附件上传和管理
- **⚡ 高性能**: Redis缓存 + 数据库优化
- **🐳 容器化**: 完整的Docker支持
- **📊 监控**: 健康检查和APM集成
- **🔒 安全**: 完善的错误处理和输入验证

## 📋 目录

- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [核心功能](#-核心功能)
- [API文档](#-api文档)
- [开发指南](#-开发指南)
- [部署说明](#-部署说明)
- [性能优化](#-性能优化)
- [故障排除](#-故障排除)

## 🚀 快速开始

### 环境要求

- **Go**: 1.25.1+
- **PostgreSQL**: 12+
- **Redis**: 6+
- **Docker**: 20.10+ (可选)
- **Protocol Buffers**: 3.15+ (开发需要)

### 快速安装

```bash
# 克隆项目
git clone bsm/full/module/base/cms.git
cd cms

# 安装依赖
go mod download

# 生成代码
make proto

# 构建应用
make build

# 运行服务
make run
```

### Docker 快速启动

```bash
# 启动完整服务栈
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f cms-service
```

## 📁 项目结构

```
cms/
├── 📁 cmd/                     # 应用程序入口
│   ├── 📁 main/               # 主服务入口
│   └── 📁 cli/                # 命令行工具
├── 📁 internal/               # 内部包
│   ├── 📁 config/             # 配置管理
│   ├── 📁 impl/               # 实现层
│   ├── 📁 logic/              # 业务逻辑
│   │   ├── 📁 category/       # 分类相关逻辑
│   │   ├── 📁 pages/          # 页面相关逻辑
│   │   ├── 📁 post/           # 文章相关逻辑
│   │   └── 📁 tags/           # 标签相关逻辑
│   ├── 📁 models/             # 数据模型
│   └── 📁 server/             # 服务器实现
├── 📁 pb/                     # Protocol Buffers 生成代码
├── 📁 proto/                  # Protocol Buffers 定义文件
├── 📁 swagger/                # API 文档
├── 📁 scripts/                # 脚本和SQL文件
├── 📁 test/                   # 测试文件
├── 📁 etc/                    # 配置文件
├── 🐳 Dockerfile              # Docker 镜像构建
├── 🐳 docker-compose.yml      # Docker 编排
├── 🔧 Makefile               # 构建脚本
└── 📖 README.md              # 项目文档
```

## 🔧 核心功能

### 1. 文章服务 (Post Service)

#### 📝 文章管理
```protobuf
rpc Create(PostItem) returns (StatusReply)
rpc Modify(PostItem) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)
```
- **功能**: 完整的文章CRUD操作
- **特性**: 
  - 支持富文本内容
  - 自动生成唯一键值
  - 支持分类和标签关联
  - 附件管理
  - 统计数据（点击量、点赞、评论等）

#### 🔍 文章查询
```protobuf
rpc GetByIdentity(GetByIdentityRequest) returns (PostItem)
rpc GetByKey(GetByKeyRequest) returns (PostItem)
rpc Search(SearchRequest) returns (SearchReply)
```
- **功能**: 多种方式查询文章
- **特性**:
  - 按ID查询
  - 按键值查询
  - 关键词搜索
  - 分类筛选
  - 分页支持

#### 💬 评论系统
```protobuf
rpc AddComment(CommentItem) returns (StatusReply)
rpc CommentList(CommentListRequest) returns (CommentListReply)
rpc ModifyComment(CommentItem) returns (StatusReply)
rpc DeleteComment(DeleteRequest) returns (StatusReply)
```
- **功能**: 完整的评论管理
- **特性**:
  - 嵌套评论支持
  - 评论计数
  - 评论点赞/踩赞

#### 👍 互动功能
```protobuf
rpc IncrPostLike(IncrPostLikeRequest) returns (StatusReply)
rpc DescPostLike(DescPostLikeRequest) returns (StatusReply)
rpc IncrPostUnlike(IncrPostUnlikeRequest) returns (StatusReply)
rpc DescPostUnlike(DescPostUnlikeRequest) returns (StatusReply)
```
- **功能**: 文章点赞/踩赞管理
- **特性**: 实时计数更新

### 2. 分类服务 (Category Service)

#### 🏷️ 分类管理
```protobuf
rpc Create(CategoryItem) returns (StatusReply)
rpc Modify(CategoryItem) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)
```
- **功能**: 层级分类管理
- **特性**:
  - 支持无限层级
  - 分类封面图片
  - 分类描述
  - 子分类预加载

### 3. 页面服务 (Pages Service)

#### 📄 页面管理
```protobuf
rpc Create(PagesItem) returns (StatusReply)
rpc Modify(PagesItem) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)
rpc GetByIdentity(GetByIdentityRequest) returns (PagesItem)
rpc GetByKey(GetByKeyRequest) returns (PagesItem)
```
- **功能**: 静态页面和动态页面管理
- **特性**:
  - 支持富文本内容
  - 标签关联
  - 附件管理
  - 多种查询方式

### 4. 标签服务 (Tags Service)

#### 🔖 标签管理
```protobuf
rpc Create(TagsItem) returns (StatusReply)
rpc Modify(TagsItem) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)
```
- **功能**: 标签系统管理
- **特性**:
  - 标签颜色支持
  - 标签描述
  - 使用统计

## 📚 API文档

### gRPC 服务

| 服务 | 方法 | 描述 | 端口 |
|------|------|------|------|
| Post | Create | 创建文章 | 12101 |
| Post | Modify | 修改文章 | 12101 |
| Post | Delete | 删除文章 | 12101 |
| Post | Fetch | 文章列表 | 12101 |
| Post | GetByIdentity | 按ID获取文章 | 12101 |
| Post | GetByKey | 按键值获取文章 | 12101 |
| Post | Search | 搜索文章 | 12101 |
| Post | AddComment | 添加评论 | 12101 |
| Post | CommentList | 评论列表 | 12101 |
| Post | ModifyComment | 修改评论 | 12101 |
| Post | DeleteComment | 删除评论 | 12101 |
| Post | IncrPostLike | 文章点赞 | 12101 |
| Post | DescPostLike | 取消文章点赞 | 12101 |
| Post | IncrPostUnlike | 文章踩赞 | 12101 |
| Post | DescPostUnlike | 取消文章踩赞 | 12101 |
| Post | IncrCommentLike | 评论点赞 | 12101 |
| Post | DescCommentLike | 取消评论点赞 | 12101 |
| Post | IncrCommentUnlike | 评论踩赞 | 12101 |
| Post | DescCommentUnlike | 取消评论踩赞 | 12101 |
| Category | Create | 创建分类 | 12101 |
| Category | Modify | 修改分类 | 12101 |
| Category | Delete | 删除分类 | 12101 |
| Category | Fetch | 分类列表 | 12101 |
| Pages | Create | 创建页面 | 12101 |
| Pages | Modify | 修改页面 | 12101 |
| Pages | Delete | 删除页面 | 12101 |
| Pages | Fetch | 页面列表 | 12101 |
| Pages | GetByIdentity | 按ID获取页面 | 12101 |
| Pages | GetByKey | 按键值获取页面 | 12101 |
| Tags | Create | 创建标签 | 12101 |
| Tags | Modify | 修改标签 | 12101 |
| Tags | Delete | 删除标签 | 12101 |
| Tags | Fetch | 标签列表 | 12101 |

### HTTP Gateway

| 端点 | 方法 | 描述 |
|------|------|------|
| `/cms.Post/Create` | POST | 创建文章 |
| `/cms.Post/Modify` | POST | 修改文章 |
| `/cms.Post/Delete` | POST | 删除文章 |
| `/cms.Post/Fetch` | POST | 文章列表 |
| `/cms.Post/GetByIdentity` | POST | 按ID获取文章 |
| `/cms.Post/GetByKey` | POST | 按键值获取文章 |
| `/cms.Post/Search` | POST | 搜索文章 |
| `/cms.Category/Create` | POST | 创建分类 |
| `/cms.Category/Modify` | POST | 修改分类 |
| `/cms.Category/Delete` | POST | 删除分类 |
| `/cms.Category/Fetch` | POST | 分类列表 |
| `/cms.Pages/Create` | POST | 创建页面 |
| `/cms.Pages/Modify` | POST | 修改页面 |
| `/cms.Pages/Delete` | POST | 删除页面 |
| `/cms.Pages/Fetch` | POST | 页面列表 |
| `/cms.Pages/GetByIdentity` | POST | 按ID获取页面 |
| `/cms.Pages/GetByKey` | POST | 按键值获取页面 |
| `/cms.Tags/Create` | POST | 创建标签 |
| `/cms.Tags/Modify` | POST | 修改标签 |
| `/cms.Tags/Delete` | POST | 删除标签 |
| `/cms.Tags/Fetch` | POST | 标签列表 |

### Swagger 文档

- **本地**: http://localhost:12102/cms.swagger.json
- **在线**: 通过 HTTP Gateway 访问完整的 API 文档

## 🛠️ 开发指南

### 开发环境设置

```bash
# 安装开发工具
make install-tools

# 设置Git钩子
git config core.hooksPath .githooks

# 启动开发模式
make dev
```

### 代码生成

```bash
# 生成 protobuf 代码
make proto

# 生成 Swagger 文档
make swagger
```

### 测试

```bash
# 运行所有测试
make test

# 测试覆盖率
make test-coverage

# gRPC 功能测试
make test-grpc

# 代码检查
make lint

# 安全扫描
make security
```

### 数据库管理

```bash
# 初始化数据库
make init-db

# 备份数据库
make backup-db
```

## 🚀 部署说明

### Docker 部署

```bash
# 构建镜像
make docker-build

# 启动服务栈
make docker-compose-up

# 查看日志
make docker-compose-logs

# 停止服务
make docker-compose-down
```

### 生产环境部署

1. **环境准备**
   ```bash
   # 创建生产配置
   cp etc/cms_dev.yaml etc/cms_prod.yaml
   # 编辑生产配置...
   ```

2. **数据库初始化**
   ```bash
   # 执行数据库迁移
   make migrate
   ```

3. **服务启动**
   ```bash
   # 构建生产版本
   make build-linux
   
   # 启动服务
   ./build/cms-linux-amd64
   ```

### Kubernetes 部署

```yaml
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cms-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: cms-service
  template:
    metadata:
      labels:
        app: cms-service
    spec:
      containers:
      - name: cms-service
        image: cms:latest
        ports:
        - containerPort: 12101
        - containerPort: 12102
        env:
        - name: SERVICE_ENV
          value: "production"
```

## ⚡ 性能优化

### 缓存策略

| 数据类型 | 缓存时间 | 策略 |
|----------|----------|------|
| 文章列表 | 10分钟 | 按分类+关键词缓存 |
| 文章详情 | 30分钟 | 按文章ID缓存 |
| 分类数据 | 1小时 | 全量缓存 |
| 标签数据 | 1小时 | 全量缓存 |
| 页面数据 | 1小时 | 按页面ID缓存 |

### 数据库优化

- **索引优化**: 关键字段建立复合索引
- **查询优化**: 使用预加载减少N+1查询
- **连接池**: 配置合适的连接池大小
- **读写分离**: 支持主从数据库配置

### 监控指标

```bash
# 服务健康检查
curl http://localhost:12102/health

# 性能指标
curl http://localhost:12102/metrics
```

## 🔧 配置说明

### 环境配置文件

```yaml
# etc/cms_prod.yaml
Service: cms
Port: 12101

# 数据库配置
Databases:
  Driver: postgres
  Source:
    - host=db-host user=postgres password=*** dbname=cms_db port=5432 sslmode=require

# 缓存配置
Cache: redis://username:password@redis-host:6379/0

# 网关配置
Gateway:
  Enable: true
  Port: 12102

# 微服务配置
MicroService:
  Enable: true
  Registry: etcd://etcd-cluster:2379

# APM监控
APM:
  Platform: elasticAPM
  Endpoint: http://apm-server:8200
```

### 环境变量

| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| `SERVICE_ENV` | 运行环境 | `development` |
| `CONFIG_FILE` | 配置文件路径 | `etc/cms_dev.yaml` |
| `LOG_LEVEL` | 日志级别 | `info` |
| `TZ` | 时区设置 | `Asia/Shanghai` |

## 🐛 故障排除

### 常见问题

1. **服务启动失败**
   ```bash
   # 检查端口占用
   netstat -tlnp | grep :12101
   
   # 检查配置文件
   make lint
   ```

2. **数据库连接失败**
   ```bash
   # 测试数据库连接
   psql -h your-db-host -U postgres -d cms_db -c "SELECT 1;"
   ```

3. **Redis连接失败**
   ```bash
   # 测试Redis连接
   redis-cli -h your-redis-host ping
   ```

### 日志分析

```bash
# 查看服务日志
tail -f logs/cms.log

# 查看错误日志
grep ERROR logs/cms.log

# 查看性能日志
grep "slow query" logs/cms.log
```

### 性能调优

1. **内存优化**
   ```bash
   # 监控内存使用
   go tool pprof http://localhost:6060/debug/pprof/heap
   ```

2. **CPU优化**
   ```bash
   # CPU性能分析
   go tool pprof http://localhost:6060/debug/pprof/profile
   ```

## 📊 数据模型

### 核心表结构

#### Cms_post - 文章表
```sql
CREATE TABLE Cms_post (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(36) UNIQUE NOT NULL,
    title VARCHAR(255) NOT NULL,
    key VARCHAR(255) UNIQUE NOT NULL,
    description VARCHAR(255) DEFAULT '',
    cover_path VARCHAR(255) DEFAULT '',
    author VARCHAR(255) DEFAULT '',
    author_identity VARCHAR(36) DEFAULT '',
    cms TEXT DEFAULT '',
    target_url VARCHAR(255) DEFAULT '',
    source_url VARCHAR(255) DEFAULT '',
    hits BIGINT DEFAULT 0,
    like_hits BIGINT DEFAULT 0,
    unlike_hits BIGINT DEFAULT 0,
    comment_hits BIGINT DEFAULT 0,
    has_accessory BOOLEAN DEFAULT false,
    type INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### Cms_category - 分类表
```sql
CREATE TABLE Cms_category (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(36) UNIQUE NOT NULL,
    category_key VARCHAR(255) UNIQUE NOT NULL,
    title VARCHAR(255) NOT NULL,
    cover_path VARCHAR(255) DEFAULT '',
    parent_id INTEGER DEFAULT 0,
    intro TEXT DEFAULT '',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP
);
```

#### Cms_pages - 页面表
```sql
CREATE TABLE Cms_pages (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(36) UNIQUE NOT NULL,
    title VARCHAR(255) NOT NULL,
    key VARCHAR(255) UNIQUE NOT NULL,
    description VARCHAR(255) DEFAULT '',
    cover_path VARCHAR(255) DEFAULT '',
    cms TEXT DEFAULT '',
    has_accessory BOOLEAN DEFAULT false,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### Cms_tags - 标签表
```sql
CREATE TABLE Cms_tags (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(36) UNIQUE NOT NULL,
    title VARCHAR(255) NOT NULL,
    color VARCHAR(7) DEFAULT '#000000',
    intro TEXT DEFAULT '',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### Cms_comment - 评论表
```sql
CREATE TABLE Cms_comment (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(36) UNIQUE NOT NULL,
    post_identity VARCHAR(36) NOT NULL,
    parent_id INTEGER DEFAULT 0,
    author VARCHAR(255) DEFAULT '',
    author_identity VARCHAR(36) DEFAULT '',
    content TEXT NOT NULL,
    like_hits BIGINT DEFAULT 0,
    unlike_hits BIGINT DEFAULT 0,
    comment_hits BIGINT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## 🤝 贡献指南

### 开发流程

1. **Fork 项目**
2. **创建特性分支**: `git checkout -b feature/amazing-feature`
3. **提交更改**: `git commit -m 'Add amazing feature'`
4. **推送分支**: `git push origin feature/amazing-feature`
5. **创建 Pull Request**

### 代码规范

- 遵循 Go 官方代码规范
- 使用 `gofmt` 格式化代码
- 添加必要的注释和文档
- 编写单元测试

### 提交规范

```
type(scope): description

[optional body]

[optional footer]
```

类型:
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式
- `refactor`: 重构
- `test`: 测试
- `chore`: 构建过程或辅助工具的变动

## 📄 许可证

本项目采用内部许可证，仅供 BSM 内部使用。

## 👥 团队

- **作者**: David Yan (david.yan@qq.com)
- **维护者**: BSM 开发团队
- **项目地址**: [bsm/full/module/base/cms](https://bsm/full/module/base/cms)

## 🔗 相关链接

- [BSM SDK](https://git.apinb.com/bsm-sdk)
- [API 文档](https://docs.apinb.com/cms)
- [问题反馈](https://bsm/full/module/base/cms/issues)

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给它一个星标！**

Made with ❤️ by BSM Team

</div>