# D8D Starter 现有系统架构文档

## 介绍

本文档记录了 D8D Starter 代码库的当前状态，包括技术债务、变通方案和实际使用模式。它作为 AI 代理进行增强开发时的参考文档。

### 文档范围
全面记录整个系统架构

### 变更日志
| 日期       | 版本 | 描述                 | 作者     |
| ---------- | ---- | -------------------- | -------- |
| 2024-09-14 | 1.0  | 初始现有系统分析 | Winston |

## 快速参考 - 关键文件和入口点

### 理解系统的关键文件
- **主入口**: `server.js` - Node.js 服务器启动文件
- **配置**: `src/server/data-source.ts` - 数据库配置
- **核心业务逻辑**: `src/server/api/` - API 路由处理
- **数据库模型**: `src/server/modules/` - TypeORM 实体
- **前端入口**: `src/client/index.tsx` - React 应用入口

## 高级架构

### 技术摘要

### 实际技术栈 (来自 package.json)

| 类别       | 技术         | 版本     | 备注                      |
| ---------- | ------------ | -------- | ------------------------- |
| 运行时     | Node.js      | 20.18.3  | ES 模块                   |
| 框架       | Hono         | 4.8.5    | Web 框架                  |
| 前端框架   | React        | 19.1.0   | 最新版本                  |
| 构建工具   | Vite         | 7.0.0    | 开发服务器和构建工具      |
| 数据库     | MySQL        | 8.0.36   | 通过 TypeORM              |
| ORM        | TypeORM      | 0.3.25   | 数据库操作                |
| 样式       | Tailwind CSS | 4.1.11   | 原子化 CSS 框架           |
| 状态管理   | React Query  | 5.83.0   | 服务端状态管理            |
| 认证       | JWT          | 9.0.2    | JSON Web Token            |

### 仓库结构现状检查
- **类型**: Monorepo (前后端在同一仓库)
- **包管理器**: pnpm (通过 pnpm-lock.yaml)
- **构建系统**: Vite + 自定义服务器配置

## 源码树和模块组织

### 项目结构 (实际)

```text
d8d-starter/
├── src/
│   ├── client/           # 前端 React 代码
│   │   ├── admin/        # 管理后台界面
│   │   ├── home/         # 用户主页界面
│   │   ├── components/   # 共享组件
│   │   ├── hooks/        # React Hooks
│   │   └── lib/          # 工具库
│   ├── server/           # 后端 Node.js 代码
│   │   ├── api/          # API 路由处理
│   │   │   ├── auth/     # 认证相关路由
│   │   │   ├── users/    # 用户管理路由
│   │   │   └── roles/    # 角色管理路由
│   │   ├── modules/      # 业务模块
│   │   ├── middleware/   # 中间件
│   │   ├── types/        # TypeScript 类型定义
│   │   └── utils/        # 工具函数
│   └── share/            # 前后端共享代码
├── dist/                 # 构建输出目录
├── scripts/              # 构建和部署脚本
└── config/               # 配置文件
```

### 关键模块及其用途
- **用户管理**: `src/server/modules/users/` - 处理所有用户操作
- **认证系统**: `src/server/api/auth/` - JWT 认证实现
- **数据库连接**: `src/server/data-source.ts` - TypeORM 数据源配置
- **API 路由**: `src/server/api.ts` - 主 API 路由配置
- **前端路由**: `src/client/admin/routes.tsx` - React Router 配置

## 数据模型和 API

### 数据模型
- **用户模型**: 参见 `src/server/modules/users/user.entity.ts`
- **角色模型**: 参见 `src/server/modules/users/role.entity.ts`
- **相关类型**: TypeScript 定义在 `src/share/types/`

### API 规范
- **OpenAPI 文档**: 通过 `/ui` 端点提供 Swagger UI
- **API 版本**: v1 (`/api/v1/` 前缀)
- **认证方式**: Bearer Token (JWT)

## 技术债务和已知问题

### 关键技术债务
1. **生产环境模板处理**: `server.js` 中的模板处理逻辑较为复杂，需要简化
2. **错误处理**: 错误处理中间件需要更完善的错误分类和日志记录
3. **环境配置**: 缺少完整的 `.env` 文件示例，环境变量管理需要改进
4. **类型安全**: 部分代码使用了 `any` 类型，需要更严格的类型定义

### 变通方案和注意事项
- **开发环境**: Vite 开发服务器与 Hono 服务器集成较为复杂
- **生产构建**: 需要分别构建客户端和服务端代码
- **数据库同步**: 开发环境下默认启用数据库同步 (`synchronize: true`)
- **静态资源**: 生产环境使用 sirv 中间件提供静态文件服务

## 集成点和外部依赖

### 外部服务
| 服务     | 用途     | 集成类型 | 关键文件                     |
| -------- | -------- | -------- | ---------------------------- |
| MySQL    | 数据库   | TypeORM  | `src/server/data-source.ts`  |
| Redis    | 缓存     | 未实现   | (计划中)                     |
| MinIO    | 对象存储 | 未实现   | (计划中)                     |

### 内部集成点
- **前后端通信**: REST API 在端口 8080
- **认证集成**: JWT token 通过 Authorization header 传递
- **数据库集成**: TypeORM 提供数据库抽象层

## 开发和部署

### 本地开发设置
1. 运行 `docker-compose up` 启动依赖服务
2. 运行 `npm run dev` 启动开发服务器
3. 访问 `http://localhost:8080`

### 构建和部署流程
- **开发构建**: `npm run dev` (Vite 开发服务器)
- **生产构建**: `npm run build` (分别构建客户端和服务端)
- **生产启动**: `npm start` (Node.js 生产服务器)

## 测试现状

### 当前测试覆盖率
- **单元测试**: 未配置测试框架
- **集成测试**: 无
- **E2E 测试**: 无
- **手动测试**: 主要 QA 方法

### 运行测试
```bash
# 目前没有配置测试命令
```

## 附录 - 有用命令和脚本

### 常用命令
```bash
npm run dev         # 启动开发服务器
npm run build       # 生产环境构建
npm start           # 启动生产服务器
docker-compose up   # 启动依赖服务
```

### 调试和故障排除
- **日志**: 查看控制台输出获取应用日志
- **调试模式**: 设置 `DEBUG=*` 环境变量获取详细日志
- **数据库**: 通过 phpMyAdmin (端口 38090) 管理数据库

## 开发注意事项

### 代码风格和约定
- **TypeScript**: 严格模式启用，建议使用严格类型
- **导入别名**: 使用 `@/` 作为 `src/` 的别名
- **错误处理**: 使用统一的错误处理中间件
- **API 设计**: 遵循 RESTful 原则，使用 OpenAPI 规范

### 性能考虑
- **数据库连接**: 使用连接池管理数据库连接
- **静态资源**: 生产环境使用压缩中间件
- **SSR 渲染**: 支持服务端渲染，但当前未完全启用

### 安全考虑
- **环境变量**: 敏感配置通过环境变量管理
- **认证**: JWT token 认证，需要实现更完善的权限控制
- **输入验证**: 使用 Zod 进行请求参数验证

这个文档提供了 D8D Starter 项目的完整架构概览，包括当前的技术债务和需要注意的事项。随着项目的演进，这个文档应该定期更新以反映最新的系统状态。