Página inicial Explorar Ajuda
Registrar Entrar
1030-6
/
d8d-vite-starter
1
0
Fork 25
Arquivos Issues 0 Pull Requests 0 Wiki
Tree: 297c267c97
Branches Tags
d8d-vite-starte...
/
docs
/
brownfield-architecture.md

brownfield-architecture.md 7.0 KB
Histórico Raw

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 + 自定义服务器配置

源码树和模块组织

项目结构 (实际)

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 方法

运行测试

# 目前没有配置测试命令

附录 - 有用命令和脚本

常用命令

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