Skip to content

Customer-serviceDocs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

Customer-serviceDocs

README.md

Customer-Service 技术文档

文档概述

本目录包含 Customer-Service 项目的完整技术文档，涵盖了系统架构、开发指南、配置管理等各个方面的内容。

文档索引

1. 系统架构文档

文件: ARCHITECTURE.md

内容:

  • 系统概述和技术栈
  • 整体架构图和数据流向
  • 核心组件说明
  • 部署架构
  • 关键业务流程
  • 安全机制
  • 性能优化
  • 扩展性设计

适合人群: 架构师、技术负责人、新加入的开发者

2. 目录结构详解

文件: STRUCTURE.md

内容:

  • 根目录结构说明
  • 核心目录详解（cmd、internal、pkg、middleware 等）
  • 每个子目录的功能和文件说明
  • 文件命名约定
  • 依赖关系图
  • 关键文件说明

适合人群: 所有开发者，特别是新加入的成员

3. 核心模块说明

文件: MODULES.md

内容:

  • 模块分类和概述
  • 各业务模块的详细说明：
    • 用户和权限管理模块
    • 游戏管理模块
    • 订单和支付模块
    • 工单和投诉模块
    • 内容审核模块
    • 通知和消息模块
    • VIP 管理模块
    • 礼品和奖励模块
    • 注销和申诉模块
    • 运营和数据模块
    • Web 服务模块
    • 外部 API 模块
  • 模块依赖关系
  • 模块间通信方式
  • 模块开发规范

适合人群: 业务开发人员、产品经理

4. 数据模型文档

文件: MODELS.md

内容:

  • 数据模型概述
  • 核心模型详细说明（用户、工单、投诉、订单、通知等）
  • 模型子目录说明
  • 数据库索引设计
  • 数据库关联关系（一对一、一对多、多对多）
  • 数据库迁移
  • 数据验证
  • 软删除机制
  • 最佳实践

适合人群: 数据库管理员、后端开发人员

5. API 路由文档

文件: ROUTES.md

内容:

  • API 概述
  • 服务端口
  • 公共路由
  • 路由分组详解：
    • 无认证路由组
    • JWT 认证路由组
    • JWT + 项目权限路由组
    • 签名验证路由组
    • Web 限流路由组
    • 微信路由组
    • 等
  • 中间件详解（JWT、CORS、权限验证等）
  • Protobuf 生成的路由
  • 响应格式
  • 常见状态码
  • 路由命名规范

适合人群: API 开发人员、前端开发人员、测试人员

6. 配置和环境文档

文件: CONFIG.md

内容:

  • 配置文件结构
  • 配置项详解（应用配置、数据库配置、防沉迷配置、SDK 访问配置等）
  • 配置加载机制
  • 环境配置（开发、测试、生产）
  • 环境变量
  • 特殊配置模块
  • 配置热更新
  • 部署配置（Docker、Kubernetes）
  • 配置调试
  • 常见问题

适合人群: 运维人员、部署工程师、开发人员

7. 开发指南

文件: DEVELOPMENT.md

内容:

  • 开发环境搭建
  • 项目结构
  • 编码规范（命名规范、代码格式化、注释规范、错误处理）
  • 开发流程：
    • 新增业务模块
    • 修改数据库
    • 修改 Protobuf
  • 测试指南（单元测试、集成测试、测试覆盖率）
  • Git 工作流
  • 构建和部署
  • 调试技巧
  • 常见问题
  • 最佳实践

适合人群: 所有开发人员

8. 外部依赖文档

文件: INTEGRATIONS.md

内容:

  • 外部服务分类
  • 游戏相关服务（game_server、item_server、anti_addiction 等）
  • 通信服务（email_server、sms、msg_server 等）
  • 内容和数据服务（content、es、obs 等）
  • 运营和 CRM 服务（vip_admin、invoice_server、dingtalk 等）
  • AI 和智能服务（ai_help_server、ai_td_server）
  • 工具和服务（db、permission、short_link 等）
  • 使用示例
  • 错误处理
  • 最佳实践

适合人群: 需要集成外部服务的开发人员

快速导航

新手入门

  1. 首先阅读 系统架构文档 了解整体架构
  2. 然后阅读 目录结构详解 熟悉项目结构
  3. 参考 开发指南 搭建开发环境

业务开发

  1. 阅读 核心模块说明 了解业务模块
  2. 参考 API 路由文档 了解接口定义
  3. 查阅 数据模型文档 了解数据结构
  4. 使用 外部依赖文档 调用外部服务

运维部署

  1. 参考 配置和环境文档 配置环境
  2. 查看 系统架构文档 了解部署架构
  3. 使用 开发指南 中的构建和部署章节

文档使用建议

阅读顺序

新加入的开发人员:

  1. ARCHITECTURE.md → 了解系统全貌
  2. STRUCTURE.md → 熟悉代码组织
  3. DEVELOPMENT.md → 搭建开发环境
  4. MODULES.md → 了解业务模块
  5. ROUTES.md → 了解 API 接口

业务开发人员:

  1. MODULES.md → 找到相关业务模块
  2. MODELS.md → 了解数据结构
  3. INTEGRATIONS.md → 了解外部服务调用
  4. DEVELOPMENT.md → 参考开发规范

运维和部署人员:

  1. ARCHITECTURE.md → 了解系统架构
  2. CONFIG.md → 配置环境
  3. DEVELOPMENT.md → 构建和部署

查找方式

文档维护

更新原则

  1. 代码变更时同步更新文档
  2. 新增功能时添加相应文档说明
  3. 修改接口时更新 API 文档
  4. 调整架构时更新架构文档

贡献指南

  1. 发现文档错误或遗漏，请及时修正
  2. 新增功能时，请补充相关文档
  3. 保持文档的准确性和完整性
  4. 使用清晰的标题和格式

相关资源

项目文档

外部资源

内部工具

  • make gen - 生成代码和文档
  • make build - 构建项目
  • make test - 运行测试

反馈和支持

如有文档相关问题或建议，请联系：

文档版本

  • 创建时间: 2026-01-27
  • 最后更新: 2026-01-27
  • 文档版本: v1.0.0

许可证

本文档遵循项目许可证。