|
|
@@ -0,0 +1,180 @@
|
|
|
+# 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 项目的完整架构概览，包括当前的技术债务和需要注意的事项。随着项目的演进，这个文档应该定期更新以反映最新的系统状态。
|
yourname