rwadurian/backend/services/admin-service/docs

Admin Service 文档中心

欢迎来到 Admin Service 文档中心！本目录包含了服务的完整技术文档。

📚 文档列表

1. ARCHITECTURE.md - 架构设计文档

内容概览:

• 服务职责和核心功能
• DDD + Hexagonal 架构设计
• 领域模型详解 (聚合根、值对象、领域服务)
• 技术栈和目录结构
• 数据流和依赖方向
• SOLID 原则应用
• 性能和安全性考量

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

关键章节:

• §2 架构设计 - 了解系统整体架构
• §3 领域设计 - 深入理解业务模型
• §6 数据流 - 掌握请求处理流程

---

2. API.md - API 接口文档

内容概览:

• API 端点完整说明
• 请求/响应格式和示例
• 错误处理和状态码
• 认证授权机制 (待实现)
• 使用示例和最佳实践

适合人群: 前端开发者、API 集成开发者、测试工程师

核心端点:

• POST /api/v1/version - 创建版本
• GET /api/v1/version/check - 检查更新 (移动端)
• PATCH /api/v1/version/:id/enable - 启用版本
• PATCH /api/v1/version/:id/disable - 禁用版本

快速开始:

# 检查更新
curl "http://localhost:3005/api/v1/version/check?platform=android&versionCode=100"

# 创建版本
curl -X POST http://localhost:3005/api/v1/version \
  -H "Content-Type: application/json" \
  -d '{"platform": "android", "versionCode": 101, ...}'

---

3. DEVELOPMENT.md - 开发指南

内容概览:

• 开发环境设置
• 项目初始化步骤
• 完整开发迭代流程
• 代码规范 (TypeScript, DDD, NestJS, Prisma)
• 调试技巧和常见开发任务

适合人群: 开发者、贡献者

推荐阅读顺序:

1. §1 开发环境设置 - 配置本地环境
2. §2 项目初始化 - 快速启动项目
3. §3 开发流程 - 学习标准开发流程
4. §4 代码规范 - 遵循团队规范

Git 工作流:

git checkout develop
git checkout -b feature/add-version-delete
# 开发...
git commit -m "feat(version): add delete version functionality"
git push origin feature/add-version-delete

---

4. TESTING.md - 测试文档

内容概览:

• 三层测试架构 (单元/集成/E2E)
• 测试环境设置 (本地/WSL2/Docker)
• 测试用例详细示例
• 测试执行方法
• 覆盖率要求和 CI/CD 集成

适合人群: 开发者、测试工程师、CI/CD 工程师

测试统计:

• 单元测试: 53 个用例, 6 个文件
• 集成测试: 21 个用例, 2 个文件
• E2E 测试: 15 个用例, 1 个文件
• 总计: ~89 个测试用例

快速运行测试:

# 单元测试 (无需数据库)
npm run test:unit

# 集成测试 (需要数据库)
DATABASE_URL="postgresql://..." npm run test:integration

# E2E 测试 (需要数据库)
DATABASE_URL="postgresql://..." npm run test:e2e

# 所有测试 + 覆盖率
npm run test:cov

---

5. DEPLOYMENT.md - 部署文档

内容概览:

• 部署架构和环境准备
• 本地部署 (PM2)
• Docker 容器化部署
• 生产环境最佳实践
• 监控、日志、备份策略
• 故障排查和回滚方案

适合人群: 运维工程师、DevOps 工程师、系统管理员

部署方式:

方式	适用场景	复杂度
本地部署 (PM2)	开发/测试环境	⭐⭐
Docker Compose	本地/小规模生产	⭐⭐⭐
Kubernetes	大规模生产	⭐⭐⭐⭐⭐

快速部署:

# Docker 方式
docker-compose up -d
docker-compose exec admin-service npx prisma migrate deploy

# PM2 方式
npm run build
pm2 start ecosystem.config.js

---

🚀 快速导航

我是新开发者

1. 阅读 ARCHITECTURE.md §1-§2 了解服务职责和架构
2. 按照 DEVELOPMENT.md §1-§2 设置开发环境
3. 查看 API.md §5-§6 熟悉 API 端点
4. 阅读 DEVELOPMENT.md §3 学习开发流程

我要集成 API

1. 阅读 API.md §1 了解基本信息
2. 查看 API.md §5 学习具体端点用法
3. 参考 API.md §7 查看使用示例
4. 查阅 API.md §4 处理错误情况

我要编写测试

1. 阅读 TESTING.md §1 了解测试架构
2. 按照 TESTING.md §2 设置测试环境
3. 参考 TESTING.md §3-§5 编写测试用例
4. 查看 TESTING.md §7 检查覆盖率

我要部署服务

1. 阅读 DEPLOYMENT.md §1 了解部署架构
2. 按照 DEPLOYMENT.md §2 准备环境
3. 选择合适的部署方式:
   • 开发: DEPLOYMENT.md §3 本地部署
   • 测试: DEPLOYMENT.md §4 Docker 部署
   • 生产: DEPLOYMENT.md §5 生产环境部署
4. 配置监控: DEPLOYMENT.md §6

我遇到问题

1. 查看 DEVELOPMENT.md §7 开发常见问题
2. 查看 TESTING.md §9 测试最佳实践
3. 查看 DEPLOYMENT.md §7 故障排查

---

📖 文档约定

版本标记

• ✅ 已实现: 功能已完成并经过测试
• ⚠️ 部分实现: 功能部分完成或待优化
• ❌ 未实现: 计划功能但尚未开发
• 🎯 目标: 性能或覆盖率目标

优先级标记

• P0: 核心功能，必须实现
• P1: 重要功能，高优先级
• P2: 常用功能，中优先级
• P3: 辅助功能，低优先级
• P4: 增强功能，可选实现

代码示例标记

// ✅ 推荐: 说明推荐的做法
const goodExample = () => {};

// ❌ 避免: 说明不推荐的做法
const badExample = () => {};

---

🔄 文档更新日志

2025-12-03 - v1.0.0 (初始版本)

• ✅ 创建完整文档体系
• ✅ ARCHITECTURE.md - 架构设计文档
• ✅ API.md - API 接口文档
• ✅ DEVELOPMENT.md - 开发指南
• ✅ TESTING.md - 测试文档
• ✅ DEPLOYMENT.md - 部署文档

---

📋 待办事项

短期 (1-3 个月)

• 添加 Swagger/OpenAPI 规范文档
• 完善 JWT 认证文档
• 添加性能测试文档
• 补充故障案例库

中期 (3-6 个月)

• 添加 Kubernetes 部署指南
• 完善监控告警文档
• 添加安全审计文档
• 补充数据迁移指南

长期 (6-12 个月)

• 添加多语言 API 客户端示例
• 完善灰度发布文档
• 添加 A/B 测试指南
• 补充性能调优案例

---

🤝 贡献指南

文档更新流程

1. 创建分支:

git checkout -b docs/update-api-examples

2. 修改文档:

• 遵循现有格式和风格
• 添加清晰的示例代码
• 更新版本日期

3. 提交变更:

git add docs/
git commit -m "docs: add API usage examples for version check"

4. 创建 Pull Request:

• 描述文档变更内容
• 标注相关 Issue
• 请求 Review

文档规范

1. Markdown 格式:

   • 使用标题层级 (H1-H6)
   • 代码块指定语言
   • 表格对齐美观

2. 命名规范:

   • 文件名大写: ARCHITECTURE.md
   • 章节使用数字编号: §1, §2
   • 代码示例清晰标注

3. 内容要求:

   • 简洁明了
   • 示例完整可运行
   • 及时更新版本信息

---

📞 联系方式

• 项目: RWA Durian
• 服务: Admin Service
• 维护团队: RWA Durian Backend Team
• 技术支持: backend-team@rwadurian.com
• 问题反馈: GitHub Issues

---

📄 许可证

本文档遵循项目许可证。

---

最后更新: 2025-12-03 文档版本: 1.0.0 维护者: RWA Durian Team