📝 docs(architecture): create brownfield architecture documentation

- add comprehensive documentation for existing system architecture
- document technical stack, repository structure and module organization
- record data models, API specifications and integration points
- identify technical debt and known issues for future improvements
- provide development, deployment guidelines and useful commands

docs/brownfield-architecture.md

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