rwadurian/backend/services/admin-service/docs/README.md

# Admin Service 文档中心

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

## 📚 文档列表

### [1. ARCHITECTURE.md](ARCHITECTURE.md) - 架构设计文档
**内容概览**:
- 服务职责和核心功能
- DDD + Hexagonal 架构设计
- 领域模型详解 (聚合根、值对象、领域服务)
- 技术栈和目录结构
- 数据流和依赖方向
- SOLID 原则应用
- 性能和安全性考量

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

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

---

### [2. API.md](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` - 禁用版本

**快速开始**:
```bash
# 检查更新
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](DEVELOPMENT.md) - 开发指南
**内容概览**:
- 开发环境设置
- 项目初始化步骤
- 完整开发迭代流程
- 代码规范 (TypeScript, DDD, NestJS, Prisma)
- 调试技巧和常见开发任务

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

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

**Git 工作流**:
```bash
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](TESTING.md) - 测试文档
**内容概览**:
- 三层测试架构 (单元/集成/E2E)
- 测试环境设置 (本地/WSL2/Docker)
- 测试用例详细示例
- 测试执行方法
- 覆盖率要求和 CI/CD 集成

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

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

**快速运行测试**:
```bash
# 单元测试 (无需数据库)
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](DEPLOYMENT.md) - 部署文档
**内容概览**:
- 部署架构和环境准备
- 本地部署 (PM2)
- Docker 容器化部署
- 生产环境最佳实践
- 监控、日志、备份策略
- 故障排查和回滚方案

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

**部署方式**:

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

**快速部署**:
```bash
# 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](ARCHITECTURE.md) §1-§2 了解服务职责和架构
2. 按照 [DEVELOPMENT.md](DEVELOPMENT.md) §1-§2 设置开发环境
3. 查看 [API.md](API.md) §5-§6 熟悉 API 端点
4. 阅读 [DEVELOPMENT.md](DEVELOPMENT.md) §3 学习开发流程

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

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

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

### 我遇到问题
1. 查看 [DEVELOPMENT.md](DEVELOPMENT.md) §7 开发常见问题
2. 查看 [TESTING.md](TESTING.md) §9 测试最佳实践
3. 查看 [DEPLOYMENT.md](DEPLOYMENT.md) §7 故障排查

---

## 📖 文档约定

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

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

### 代码示例标记
```typescript
// ✅ 推荐: 说明推荐的做法
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. **创建分支**:
```bash
git checkout -b docs/update-api-examples
```

2. **修改文档**:
- 遵循现有格式和风格
- 添加清晰的示例代码
- 更新版本日期

3. **提交变更**:
```bash
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](https://github.com/your-org/rwa-durian/issues)

---

## 📄 许可证

本文档遵循项目许可证。

---

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