📝 docs(architecture): create enhanced architecture documentation

- add comprehensive architecture documentation for D8D Starter project
- document existing project analysis including current state and constraints
- define enhancement scope and integration strategies
- detail technical stack, data models, and component architecture
- provide API design and source code organization guidelines
- outline infrastructure, deployment, and testing strategies
- include security considerations and next implementation steps

docs/architecture.md

@@ -0,0 +1,363 @@
+# D8D Starter 遗留系统增强架构
+
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.0 | 2025-09-14 | 增强架构文档 | Winston |
+
+## 介绍
+
+本文档定义了D8D Starter项目的架构增强方案，基于对现有代码的深度分析。主要目标是将技术实现转化为明确的业务价值主张，同时保持与现有系统的完全兼容。
+
+### 文档范围
+全面定义系统增强的架构方法和集成策略
+
+### 变更日志
+| 日期 | 版本 | 描述 | 作者 |
+|------|------|------|------|
+| 2024-09-14 | 1.0 | 初始现有系统分析 | Winston |
+| 2025-09-14 | 2.0 | 增强架构文档 | Winston |
+
+## 现有项目分析
+
+### 当前项目状态
+- **主要用途**: 现代化的全栈Web应用启动模板，专注于开发者体验
+- **技术栈总结**: Node.js 20.18.3 + Hono 4.8.5 + React 19.1.0 + TypeORM 0.3.25 + MySQL 8.0.36
+- **架构风格**: 分层架构，前后端分离但统一仓库管理
+- **部署方式**: Docker Compose本地开发，Node.js生产部署
+
+### 可用文档分析
+✅ **技术文档完整**:
+- 技术栈和版本信息准确
+- 源码结构和模块组织清晰
+- 数据模型定义完整
+- API规范通过OpenAPI自动生成
+
+⚠️ **需要补充**:
+- 完整的业务需求文档
+- 测试策略和覆盖率
+- 性能优化指南
+- 安全最佳实践
+
+### 识别出的约束
+- 必须保持与现有shadcn设计系统的兼容性
+- 需要支持MySQL关系型数据库
+- 前端构建基于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 | 开发服务器和构建 | 热重载支持 |
+| 数据库 | 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 | 用户认证和安全 | Bearer Token |
+
+### 新技术添加
+| 技术 | 版本 | 用途 | Rationale | 集成方法 |
+|------|------|------|-----------|-----------|
+| Jest | 29.x | 单元测试框架 | 填补测试空白，确保代码质量 | 集成到现有构建流程 |
+| Testing Library | 13.x | React组件测试 | 提供组件级测试能力 | 与React项目集成 |
+| Supertest | 6.x | API端点测试 | 验证API功能和集成 | 与Hono服务器集成 |
+
+## 数据模型和Schema变更
+
+### 数据模型增强
+**用户模型增强**:
+- **用途**: 完善用户管理和权限系统
+- **集成**: 扩展现有User实体，添加更好的验证和关系处理
+- **关键属性**:
+  - `id`: number - 主键标识符
+  - `email`: string - 唯一邮箱地址
+  - `password`: string - 加密密码
+  - `roles`: Role[] - 用户角色关系
+- **关系**:
+  - **与现有**: 保持与Role实体的多对多关系
+  - **与新**: 无新关系，优化现有关系处理
+
+### Schema集成策略
+- **数据库变更要求**: 无新表创建，仅优化现有表结构
+- **新表**: 无
+- **修改的表**: 无结构性变更
+- **新索引**: 考虑为常用查询字段添加索引
+- **迁移策略**: 无破坏性变更，使用TypeORM迁移工具
+
+### 向后兼容性
+- 保持所有现有API端点不变
+- 确保现有数据查询继续正常工作
+- 不修改任何现有字段定义
+- 新增功能通过可选字段或新端点实现
+
+## 组件架构
+
+### 新组件
+**通用CRUD服务增强**:
+- **责任**: 提供类型安全的通用CRUD操作，支持自定义扩展
+- **集成点**: 与现有API路由和TypeORM实体集成
+- **关键接口**:
+  - `createCrudRoutes()` - 创建标准CRUD路由
+  - `withCustomOperations()` - 添加自定义业务逻辑
+- **依赖关系**:
+  - **现有组件**: TypeORM Repository, Hono Router
+  - **新组件**: 测试工具和验证工具
+- **技术栈**: TypeScript, Hono RPC, Zod验证
+
+**API文档组件**:
+- **责任**: 自动生成和维护OpenAPI文档
+- **集成点**: 集成@hono/zod-openapi到现有路由
+- **关键接口**:
+  - `generateOpenAPISpec()` - 从路由生成OpenAPI规范
+  - `serveSwaggerUI()` - 提供交互式文档界面
+
+### 组件交互
+```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/        # 管理后台界面
+│   │   ├── home/         # 用户主页界面
+│   │   ├── components/   # 共享组件
+│   │   ├── hooks/        # React Hooks
+│   │   └── lib/          # 工具库
+│   ├── server/           # Node.js后端代码
+│   │   ├── api/          # API路由处理
+│   │   │   ├── auth/     # 认证路由
+│   │   │   ├── users/    # 用户管理路由
+│   │   │   └── roles/    # 角色管理路由
+│   │   ├── modules/      # 业务模块
+│   │   ├── middleware/   # 中间件
+│   │   ├── types/        # TypeScript类型
+│   │   └── utils/        # 工具函数
+│   └── share/            # 前后端共享代码
+```
+
+### 新文件组织
+```text
+d8d-starter/
+├── src/
+│   ├── client/           # 现有结构保持不变
+│   ├── server/
+│   │   ├── api/
+│   │   │   ├── users/
+│   │   │   │   ├── __tests__/          # 新增：API测试
+│   │   │   │   ├── [id]/
+│   │   │   │   ├── get.ts
+│   │   │   │   └── index.ts
+│   │   ├── modules/
+│   │   │   ├── users/
+│   │   │   │   ├── __tests__/          # 新增：服务测试
+│   │   │   │   ├── user.entity.ts
+│   │   │   │   ├── user.service.ts
+│   │   │   │   └── role.entity.ts
+│   │   └── utils/
+│   │       ├── __tests__/              # 新增：工具测试
+│   │       ├── generic-crud.service.ts
+│   │       ├── generic-crud.routes.ts
+│   │       └── errorHandler.ts         # 需要增强的错误处理
+│   └── share/            # 现有结构保持不变
+```
+
+### 集成指南
+- **文件命名**: 保持现有kebab-case命名约定
+- **文件夹组织**: 遵循功能模块划分，添加__tests__文件夹
+- **导入/导出模式**: 使用ES模块，保持现有别名系统（@/）
+
+## 基础设施和部署集成
+
+### 现有基础设施
+- **当前部署**: Docker Compose本地开发，Node.js生产部署
+- **基础设施工具**: Docker, Docker Compose, Node.js运行时
+- **环境**: 开发、生产环境配置
+
+### 增强部署策略
+- **部署方法**: 使用现有Docker Compose和Node.js部署流程
+- **基础设施变更**: 无重大变更，仅优化配置
+- **流水线集成**: 集成测试到现有CI/CD流程
+
+### 回滚策略
+- **回滚方法**: Docker镜像版本回滚 + 数据库备份
+- **风险缓解**: 蓝绿部署或金丝雀发布（可选）
+- **监控**: 添加应用健康检查和性能监控
+
+## 编码标准和测试策略
+
+### 现有标准合规性
+- **代码风格**: TypeScript严格模式，一致的缩进和命名
+- **linting规则**: 需要配置ESLint/Prettier
+- **测试模式**: 无现有测试框架配置
+- **文档风格**: 代码注释良好，但缺少完整文档
+
+### 增强特定标准
+- **测试框架**: 添加Jest + Testing Library + Supertest
+- **测试位置**: `__tests__` 文件夹与源码并列
+- **覆盖率目标**: 核心业务逻辑 > 80%
+- **测试类型**: 单元测试、集成测试、E2E测试
+
+### 关键集成规则
+- **现有API兼容性**: 确保测试不破坏现有API契约
+- **数据库集成**: 使用测试数据库，避免污染生产数据
+- **错误处理**: 测试各种错误场景和边界条件
+- **日志一致性**: 测试日志格式和错误信息
+
+## 安全集成
+
+### 现有安全措施
+- **认证**: JWT Bearer Token实现完整
+- **授权**: 基础角色权限管理
+- **数据保护**: 密码使用bcrypt哈希
+- **安全工具**: 基本中间件保护
+
+### 增强安全要求
+- **新安全措施**: 添加输入验证、速率限制、CSP头
+- **集成点**: 中间件层、API网关、数据库层
+- **合规要求**: 遵循OWASP Top 10安全最佳实践
+
+### 安全测试
+- **现有安全测试**: 无自动化安全测试
+- **新安全测试要求**: 添加安全扫描、渗透测试计划
+- **渗透测试**: 计划季度安全审计
+
+## 检查清单结果报告
+
+### 架构师检查清单执行结果
+✅ **技术栈验证**: Node.js + Hono + React + TypeORM 验证通过
+✅ **架构模式**: 分层架构、模块化设计验证通过
+✅ **代码质量**: 类型安全、错误处理需要增强
+✅ **安全性**: 基础安全措施存在，需要加强
+✅ **测试覆盖**: 需要添加完整测试基础设施
+✅ **部署策略**: Docker部署成熟稳定
+
+### 需要立即修复的安全漏洞
+1. **密码安全漏洞**: UserService第121行存在明文密码比较风险
+2. **错误信息泄露**: 部分错误信息可能包含敏感细节
+3. **输入验证缺失**: 需要加强业务规则验证
+
+## 下一步骤
+
+### 故事经理交接
+基于此架构文档，开始实现以下故事：
+1. 完善用户认证和管理功能（参考现有UserService）
+2. 增强通用CRUD服务和API文档（利用现有通用CRUD基础）
+3. 重点关注现有系统兼容性和错误处理统一
+
+### 开发者交接
+开始实现时注意：
+- 保持与现有shadcn设计系统兼容
+- 遵循现有的TypeORM实体模式和API路由结构
+- 优先修复已识别的安全漏洞（密码比较逻辑）
+- 逐步添加测试覆盖，从核心业务逻辑开始
+
+### 关键集成验证点
+- 确保新功能不破坏现有API契约
+- 验证数据库迁移不会丢失现有数据
+- 测试生产环境部署流程仍然正常工作
+- 监控性能指标确保无退化
+
+## 附录
+
+### 技术决策依据
+- **选择Jest而不是Vitest**: 基于生态成熟度、企业采用率和功能完整性
+- **保持现有技术栈**: 现有选择（Hono、TypeORM、React）已经验证有效
+- **增量增强策略**: 最小化风险，最大化现有投资回报
+
+### 相关文档
+- 现有架构文档: `docs/brownfield-architecture.md`
+- 产品需求文档: `docs/prd.md`
+- API文档: 通过 `/ui` 端点访问
+
+### 联系方式
+- 架构师: Winston 🏗️
+- 最后更新: 2025-09-14
+
+---
+
+**文档状态**: 正式版
+**下次评审**: 2025-10-14