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)

技术债务和已知问题

关键技术债务

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

变通方案和注意事项

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

集成点和外部依赖

外部服务

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

内部集成点

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

开发和部署

本地开发设置

运行 docker-compose up 启动依赖服务
运行 npm run dev 启动开发服务器
访问 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 项目的完整架构概览，包括当前的技术债务和需要注意的事项。随着项目的演进，这个文档应该定期更新以反映最新的系统状态。

brownfield-architecture.md 7.0 KB History Raw

D8D Starter 现有系统架构文档

介绍

文档范围

变更日志

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

理解系统的关键文件

高级架构

技术摘要

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

仓库结构现状检查

源码树和模块组织

项目结构 (实际)

关键模块及其用途

数据模型和 API

数据模型

API 规范

技术债务和已知问题

关键技术债务

变通方案和注意事项

集成点和外部依赖

外部服务

内部集成点

开发和部署

本地开发设置

构建和部署流程

测试现状

当前测试覆盖率

运行测试

附录 - 有用命令和脚本

常用命令

调试和故障排除

开发注意事项

代码风格和约定

性能考虑

安全考虑

brownfield-architecture.md 7.0 KB

History Raw