# D8D Starter 遗留系统增强架构 ## 版本信息 | 版本 | 日期 | 描述 | 作者 | |------|------|------|------| | 2.0 | 2025-09-14 | 增强架构文档 | Winston | | 2.1 | 2025-09-19 | 添加数据库定时备份策略 | Winston | | 2.2 | 2025-09-19 | 更新测试策略文档引用 | Winston | | 2.3 | 2025-09-20 | 根据实际项目结构更新测试架构和共享目录 | Winston | ## 介绍 本文档定义了D8D Starter项目的架构增强方案，基于对现有代码的深度分析。主要目标是将技术实现转化为明确的业务价值主张，同时保持与现有系统的完全兼容。 **注意**: 本项目的详细架构文档已拆分为多个子文档，位于 `docs/architecture/` 目录中。如需查看完整的架构文档结构，请参阅 [架构文档索引](./architecture/index.md)。 ### 文档范围 全面定义系统增强的架构方法和集成策略 ### 变更日志 | 日期 | 版本 | 描述 | 作者 | |------|------|------|------| | 2024-09-14 | 1.0 | 初始现有系统分析 | Winston | | 2025-09-14 | 2.0 | 增强架构文档 | Winston | | 2025-09-19 | 2.1 | 添加数据库定时备份策略 | Winston | | 2025-09-19 | 2.2 | 更新测试策略文档引用 | Winston | | 2025-09-20 | 2.3 | 根据实际项目结构更新测试架构和共享目录 | Winston | ## 现有项目分析 ### 当前项目状态 - **主要用途**: 现代化的全栈Web应用启动模板，专注于开发者体验 - **技术栈总结**: Node.js 20.18.3 + Hono 4.8.5 + React 19.1.0 + TypeORM 0.3.25 + PostgreSQL 15 - **架构风格**: 分层架构，前后端分离但统一仓库管理 - **部署方式**: Docker Compose本地开发，Node.js生产部署 ### 可用文档分析 ✅ **技术文档完整**: - 技术栈和版本信息准确 - 源码结构和模块组织清晰 - 数据模型定义完整 - API规范通过OpenAPI自动生成 ⚠️ **需要补充**: - 完整的业务需求文档 - 测试策略和覆盖率 - 性能优化指南 - 安全最佳实践 ### 识别出的约束 - 必须保持与现有shadcn设计系统的兼容性 - 需要支持PostgreSQL关系型数据库 - 前端构建基于Vite，后端基于Hono - 部署环境支持Docker容器化 - 现有代码中存在一些`any`类型需要修复 ## 增强范围和集成策略 ### 增强概述 - **增强类型**: 现有项目功能完善和业务需求文档化 - **范围**: 将技术实现转化为明确的业务价值主张 - **集成影响级别**: 中等 - 主要添加文档和优化，不改变核心架构 ### 集成方法 - **代码集成策略**: 增量改进，保持向后兼容 - **数据库集成**: 无模式变更，仅优化查询和索引 - **API集成**: 保持现有API不变，增强文档和错误处理 - **UI集成**: 保持现有shadcn设计系统，优化用户体验 ### 兼容性要求 - **现有API兼容性**: 100%保持，不破坏现有客户端 - **数据库Schema兼容性**: 无变更，确保数据完整性 - **UI/UX一致性**: 遵循现有设计模式，保持视觉统一 - **性能影响**: 响应时间保持在100ms以内，无性能退化 ## 技术栈 ### 现有技术栈维护 | 类别 | 当前技术 | 版本 | 在增强中的用途 | 备注 | |------|----------|------|----------------|------| | 运行时 | Node.js | 20.18.3 | 服务器运行时环境 | ES模块支持 | | 框架 | Hono | 4.8.5 | Web框架和API路由 | RPC类型安全 | | 前端框架 | React | 19.1.0 | 用户界面构建 | 最新版本 | | 构建工具 | Vite | 7.0.0 | 开发服务器和构建 | 热重载支持 | | 数据库 | PostgreSQL | 15 | 数据持久化存储 | 通过TypeORM | | ORM | TypeORM | 0.3.25 | 数据库操作抽象 | 实体管理 | | 样式 | Tailwind CSS | 4.1.11 | 原子化CSS框架 | 设计一致性 | | 状态管理 | React Query | 5.83.0 | 服务端状态管理 | 数据同步 | | 认证 | JWT | 9.0.2 | 用户认证和安全 | Bearer Token | ### 新技术添加 | 技术 | 版本 | 用途 | Rationale | 集成方法 | |------|------|------|-----------|-----------| | Vitest | 2.x | 单元测试框架 | 填补测试空白，确保代码质量，更好的TypeORM支持 | 集成到现有构建流程 | | Testing Library | 13.x | React组件测试 | 提供组件级测试能力 | 与React项目集成 | | hono/testing | 内置 | API端点测试 | 验证API功能和集成 | Hono官方测试工具，更好的类型安全 | | node-cron | latest | 定时任务调度 | Node.js定时任务调度库 | 集成到应用启动流程 | ## 数据模型和Schema变更 ### 现有数据模型状态 **用户模型**: - **现状**: 设计良好，包含完整的用户管理和权限系统 - **关键属性**: - `id`: number - 主键标识符 - `username`: string - 唯一用户名（主要登录标识） - `email`: string | null - 可选邮箱地址 - `password`: string - 加密密码（bcrypt哈希） - `roles`: Role[] - 用户角色多对多关系 - **关系**: 与Role实体建立正确的多对多关系映射 **优化重点**: 保持现有数据模型不变，仅优化查询性能和验证逻辑 ### Schema集成策略 - **数据库变更要求**: 无新表创建，仅优化现有表结构 - **新表**: 无 - **修改的表**: 无结构性变更 - **新索引**: 考虑为常用查询字段添加索引 - **迁移策略**: 无破坏性变更，使用TypeORM迁移工具 ### 向后兼容性 - 保持所有现有API端点不变 - 确保现有数据查询继续正常工作 - 不修改任何现有字段定义 - 新增功能通过可选字段或新端点实现 ## 组件架构 ### 前端组件架构 **实际项目组件组织**: ```text src/client/ ├── admin/ # 管理后台应用 │ ├── components/ # 管理后台专用组件 │ │ ├── ProtectedRoute.tsx # 路由保护组件 │ │ ├── ErrorPage.tsx # 错误页面 │ │ └── NotFoundPage.tsx # 404页面 │ ├── hooks/ # 管理后台Hooks │ │ └── AuthProvider.tsx # 认证状态管理 │ ├── layouts/ # 布局组件 │ │ └── MainLayout.tsx # 主布局 │ ├── pages/ # 页面组件 │ │ ├── Dashboard.tsx # 仪表板 │ │ ├── Login.tsx # 登录页面 │ │ └── Users.tsx # 用户管理 │ ├── routes.tsx # 路由配置 │ └── index.tsx # 管理后台入口 ├── home/ # 用户前台应用 ├── components/ # 共享UI组件 │ └── ui/ # shadcn/ui组件库（50+组件） │ ├── button.tsx # 按钮组件 │ ├── input.tsx # 输入框组件 │ ├── table.tsx # 表格组件 │ └── ... # 其他组件 ├── hooks/ # 共享Hooks ├── lib/ # 工具库 ├── utils/ # 工具函数 └── api.ts # API客户端配置 ``` **技术栈配置**: - **前端框架**: React 19.1.0 + TypeScript - **路由**: React Router v7 - **状态管理**: @tanstack/react-query (服务端状态) + Context (本地状态) - **UI组件库**: shadcn/ui (基于Radix UI) - **构建工具**: Vite 7.0.0 - **样式**: Tailwind CSS 4.1.11 - **HTTP客户端**: 基于Hono Client的封装 + axios适配器 ### 后端组件架构 **实际后端项目结构**: ```text src/server/ ├── api/ # API路由层 │ ├── auth/ # 认证相关路由 │ │ ├── login.ts # 登录路由 │ │ ├── logout.ts # 登出路由 │ │ └── register.ts # 注册路由 │ ├── users/ # 用户管理路由 │ │ ├── index.ts # 用户列表路由 │ │ ├── [id].ts # 用户详情路由 │ │ └── __tests__/ # 路由测试 │ ├── roles/ # 角色管理路由 │ └── __integration_tests__/ # 集成测试 ├── modules/ # 业务模块层 │ ├── auth/ # 认证业务模块 │ │ ├── auth.service.ts # 认证服务 │ │ └── __tests__/ # 认证测试 │ ├── users/ # 用户业务模块 │ │ ├── user.entity.ts # 用户实体 │ │ ├── user.service.ts # 用户服务 │ │ └── __tests__/ # 用户测试 ├── utils/ # 工具层 │ ├── generic-crud.service.ts # 通用CRUD服务 │ ├── generic-crud.routes.ts # 通用CRUD路由 │ ├── errorHandler.ts # 错误处理 │ ├── backup.ts # 数据库备份工具 │ ├── restore.ts # 数据库恢复工具 │ ├── logger.ts # 日志工具 │ └── __tests__/ # 工具测试 ├── middleware/ # 中间件层 │ ├── auth.ts # 认证中间件 │ └── validation.ts # 验证中间件 ├── types/ # 类型定义 ├── data-source.ts # 数据库连接配置 └── index.ts # 服务器入口 ``` **后端技术栈配置**: - **框架**: Hono 4.8.5 + TypeScript - **数据库**: PostgreSQL 15 + TypeORM 0.3.25 - **验证**: Zod schema验证 - **认证**: JWT Bearer Token - **API文档**: @hono/zod-openapi + Swagger UI - **测试**: Vitest + hono/testing ### 通用CRUD服务 - **责任**: 提供类型安全的通用CRUD操作，支持自定义扩展 - **现状**: 已实现完整功能，支持关联查询和复杂操作 - **文件位置**: `src/server/utils/generic-crud.service.ts` - **路由生成**: `src/server/utils/generic-crud.routes.ts` - **优化重点**: 增强错误处理、添加测试覆盖、优化性能 ### API文档组件 - **责任**: 自动生成和维护OpenAPI文档 - **现状**: 通过@hono/zod-openapi集成，提供Swagger UI - **访问路径**: `/ui` 端点 - **优化重点**: 完善文档示例、确保文档与代码同步 ### 组件交互 ```mermaid graph TD A[前端React组件] --> B[Hono API路由] B --> C[通用CRUD服务] C --> D[TypeORM实体] C --> E[Zod验证] B --> F[OpenAPI文档生成] F --> G[Swagger UI] style A fill:#e1f5fe style B fill:#f3e5f5 style C fill:#fff3e0 style D fill:#e8f5e8 ``` ## API设计和集成 ### API集成策略 - **API集成策略**: 保持现有RESTful API设计，增强OpenAPI文档 - **认证**: JWT Bearer Token，保持现有认证机制 - **版本控制**: 使用v1前缀 (`/api/v1/`)，保持向后兼容 ### API端点示例 **用户管理端点**: - **方法**: GET - **端点**: `/api/v1/users` - **用途**: 获取用户分页列表 - **集成**: 使用通用CRUD服务，支持搜索和过滤 **请求示例**: ```json { "page": 1, "pageSize": 10, "keyword": "搜索词", "sortBy": "createdAt", "sortOrder": "DESC" } ``` **响应示例**: ```json { "data": [ { "id": 1, "email": "user@example.com", "roles": [{"id": 1, "name": "admin"}] } ], "pagination": { "total": 100, "current": 1, "pageSize": 10 } } ``` ## 源码树和文件组织 ### 实际项目结构 ```text d8d-starter/ ├── src/ │ ├── client/ # React前端应用 │ │ ├── admin/ # 管理后台应用 │ │ │ ├── components/ # 管理后台组件 │ │ │ ├── hooks/ # 管理后台Hooks │ │ │ ├── layouts/ # 布局组件 │ │ │ ├── pages/ # 页面组件 │ │ │ ├── routes.tsx # 路由配置 │ │ │ └── index.tsx # 入口文件 │ │ ├── home/ # 用户前台应用（待开发） │ │ ├── components/ # 共享UI组件 │ │ │ └── ui/ # shadcn/ui组件库 │ │ ├── hooks/ # 共享Hooks │ │ ├── lib/ # 工具库 │ │ ├── utils/ # 工具函数 │ │ ├── api.ts # API客户端 │ │ └── index.tsx # 前端入口 │ ├── server/ # Hono后端应用 │ │ ├── api/ # API路由 │ │ ├── modules/ # 业务模块 │ │ ├── middleware/ # 中间件 │ │ └── index.ts # 服务器入口 │ └── share/ # 前后端共享代码 │ └── types.ts # TypeScript类型定义 ├── tests/ │ └── e2e/ # E2E测试 (Playwright) └── package.json ``` ### 集成指南 - **文件命名**: 保持现有kebab-case命名约定 - **文件夹组织**: 遵循功能模块划分，添加__tests__文件夹 - **导入/导出模式**: 使用ES模块，保持现有别名系统（@/） ## 基础设施和部署集成 ### 现有基础设施 - **当前部署**: Docker Compose本地开发，Node.js生产部署 - **基础设施工具**: Docker, Docker Compose, Node.js运行时 - **环境**: 开发、生产环境配置 ### 增强部署策略 - **部署方法**: 使用现有Docker Compose和Node.js部署流程 - **基础设施变更**: 添加数据库定时备份系统（详见基础设施部署文档） - **流水线集成**: 集成测试到现有CI/CD流程 ### 回滚策略 - **回滚方法**: Docker镜像版本回滚 + 数据库备份恢复 - **数据库恢复**: 使用最新备份文件进行快速恢复 - **风险缓解**: 蓝绿部署或金丝雀发布（可选） - **监控**: 添加应用健康检查、性能监控和备份状态监控 ## 开发工作流 **实际开发命令**: ```bash # 安装依赖 pnpm install # 启动完整开发环境（前后端同时运行） pnpm dev # 运行测试 pnpm test # 运行API测试 (Vitest) pnpm test:api # 运行API测试 pnpm test:components # 运行组件测试 pnpm test:integration # 运行集成测试 (同test:components) pnpm test:e2e # 运行E2E测试 pnpm test:e2e:chromium # 运行Chrome E2E测试 pnpm test:e2e:ui # 运行E2E测试UI模式 pnpm test:e2e:debug # 运行E2E调试模式 # 代码质量检查 pnpm lint # ESLint检查 pnpm typecheck # TypeScript类型检查 pnpm test:coverage # 生成测试覆盖率报告 # 数据库相关 pnpm db:backup # 数据库备份 pnpm db:restore # 数据库恢复 pnpm db:backup:list # 列出备份文件 pnpm db:backup:latest # 获取最新备份 pnpm db:backup:cleanup # 清理旧备份 pnpm db:migrate # 数据库迁移 pnpm db:seed # 数据库种子数据 pnpm db:reset # 重置数据库 ``` **环境配置**: ```bash # 前端环境变量 (Vite) VITE_API_BASE_URL=http://localhost:3000/api # 后端环境变量 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres JWT_SECRET=your-jwt-secret-key NODE_ENV=development ``` ## 编码标准和测试策略 ### 现有标准合规性 - **代码风格**: TypeScript严格模式，一致的缩进和命名 - **linting规则**: 需要配置ESLint/Prettier - **测试模式**: 完整的测试框架已配置（Vitest + Testing Library + Playwright） - **文档风格**: 代码注释良好，测试策略文档完整 ### 增强特定标准 - **测试框架**: 使用Vitest + Testing Library + hono/testing + Playwright - **测试位置**: `__tests__` 文件夹与源码并列 - **覆盖率目标**: 核心业务逻辑 > 80% - **测试类型**: 单元测试、集成测试、E2E测试 - **测试策略**: 详见 [测试策略文档](./testing-strategy.md) ### 测试策略 **实际测试结构**: ```text tests/ └── e2e/ # E2E测试 (Playwright) ├── fixtures/ # 测试夹具数据 │ ├── test-users.json # 测试用户数据 │ ├── roles.json # 角色数据 │ └── test-data.ts # TypeScript测试数据 ├── pages/ # 页面对象模型 │ └── admin/ # 管理后台页面对象 │ ├── login.page.ts # 登录页面对象 │ ├── dashboard.page.ts # 仪表板页面对象 │ └── user-management.page.ts # 用户管理页面对象 ├── specs/ # 测试规范 │ └── admin/ # 管理后台E2E测试 │ ├── dashboard.spec.ts # 仪表板测试 │ ├── login.spec.ts # 登录测试 │ ├── settings.spec.ts # 设置测试 │ └── users.spec.ts # 用户管理测试 ├── utils/ # 测试工具 │ └── test-setup.ts # 测试设置工具 ├── global-setup.ts # 全局设置 ├── global-teardown.ts # 全局清理 └── playwright.config.ts # Playwright配置 ``` **前端测试位置**: ```text src/client/ ├── __integration_tests__/ # 前端集成测试 │ └── admin/ # 管理后台集成测试 │ ├── dashboard.test.tsx # 仪表板集成测试 │ ├── login.test.tsx # 登录集成测试 │ └── users.test.tsx # 用户管理集成测试 └── admin/ └── pages/ └── __tests__/ # 页面单元测试 ├── Users.test.tsx # 用户页面单元测试 └── debug.test.tsx # 调试页面单元测试 ``` **后端测试位置**: ```text src/server/ ├── api/ │ ├── auth/ # 认证API │ │ └── __tests__/ # 认证测试 │ │ └── auth.integration.test.ts # 认证集成测试 │ └── users/ # 用户API │ └── __tests__/ # 用户测试 │ └── users.integration.test.ts # 用户集成测试 ├── modules/ │ └── users/ # 用户业务模块 │ └── __tests__/ # 用户服务测试 │ └── user.service.test.ts # 用户服务单元测试 └── utils/ ├── __tests__/ # 工具单元测试 │ ├── backup.test.ts # 备份工具测试 │ └── restore.test.ts # 恢复工具测试 └── __integration_tests__/ # 工具集成测试 └── backup.integration.test.ts # 备份集成测试 ``` **测试框架配置**: - **单元测试**: Vitest + Testing Library (前端) / Vitest + hono/testing (后端) - **集成测试**: Vitest + 自定义测试工具 - **E2E测试**: Playwright - **测试覆盖率**: 核心业务逻辑 > 80% - **测试位置**: `__tests__` 文件夹与源码并列 ### 关键集成规则 - **现有API兼容性**: 确保测试不破坏现有API契约 - **数据库集成**: 使用测试数据库，避免污染生产数据 - **错误处理**: 测试各种错误场景和边界条件 - **日志一致性**: 测试日志格式和错误信息 ## 安全集成 ### 现有安全措施 - **认证**: JWT Bearer Token实现完整 - **授权**: 基础角色权限管理 - **数据保护**: 密码使用bcrypt哈希 - **安全工具**: 基本中间件保护 ### 增强安全要求 - **新安全措施**: 添加输入验证、速率限制、CSP头 - **集成点**: 中间件层、API网关、数据库层 - **合规要求**: 遵循OWASP Top 10安全最佳实践 ### 安全测试 - **现有安全测试**: 无自动化安全测试 - **新安全测试要求**: 添加安全扫描、渗透测试计划 - **渗透测试**: 计划季度安全审计 ## 检查清单结果报告 ### 架构师检查清单执行结果 ✅ **技术栈验证**: Node.js + Hono + React + TypeORM 验证通过 ✅ **架构模式**: 分层架构、模块化设计验证通过 ✅ **代码质量**: 类型安全、错误处理需要增强 ✅ **安全性**: 基础安全措施存在，需要加强 ✅ **测试覆盖**: 完整的测试基础设施已建立（Vitest + Testing Library + Playwright） ✅ **部署策略**: Docker部署成熟稳定 ✅ **备份策略**: 数据库定时备份方案已设计 ### 需要立即修复的安全漏洞 1. **密码安全漏洞**: UserService第121行存在明文密码比较风险 2. **错误信息泄露**: 部分错误信息可能包含敏感细节 3. **输入验证缺失**: 需要加强业务规则验证 ## 下一步骤 ### 故事经理交接 基于此架构文档，开始实现以下故事： 1. 完善用户认证和管理功能（参考现有UserService） 2. 增强通用CRUD服务和API文档（利用现有通用CRUD基础） 3. 重点关注现有系统兼容性和错误处理统一 ### 开发者交接 开始实现时注意： - 保持与现有shadcn设计系统兼容 - 遵循现有的TypeORM实体模式和API路由结构 - 优先修复已识别的安全漏洞（密码比较逻辑） - 逐步添加测试覆盖，从核心业务逻辑开始 ### 关键集成验证点 - 确保新功能不破坏现有API契约 - 验证数据库迁移不会丢失现有数据 - 测试生产环境部署流程仍然正常工作 - 监控性能指标确保无退化 ## 附录 ### 技术决策依据 - **选择Vitest而不是Jest**: 基于对TypeORM装饰器的更好支持、更快的执行速度和现代化的开发体验 - **保持现有技术栈**: 现有选择（Hono、TypeORM、React）已经验证有效 - **增量增强策略**: 最小化风险，最大化现有投资回报 ### 相关文档 - 架构文档: `docs/architecture.md` (本文件) - 架构详细文档: `docs/architecture/` (包含组件架构、API设计、技术栈等子文档) - 产品需求文档: `docs/prd.md` - 测试策略文档: `docs/architecture/testing-strategy.md` - API文档: 通过 `/ui` 端点访问 ### 联系方式 - 架构师: Winston 🏗️ - 最后更新: 2025-09-20 --- **文档状态**: 正式版 **下次评审**: 2025-10-14