huhao/ylt_diy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 创建本地运行详细指南

Browse Source 
新增 README.md 文件，包含完整的本地运行指南：

1. 系统要求说明
   - Node.js 20+（推荐）
   - pnpm（包管理器）
   - PM2（可选，生产环境）

2. 详细安装步骤
   - Node.js安装（Windows/macOS/Linux）
   - pnpm安装命令
   - 项目依赖安装
   - 数据库初始化方法

3. 运行命令总结
   - pnpm install（安装依赖）
   - pnpm run dev（开发环境）
   - pnpm run build（构建）
   - pnpm run start（生产环境）

4. 常见问题解决
   - pnpm安装失败
   - Node.js版本过低
   - 数据库连接失败
   - 端口占用
   - Excel下载问题
   - 定时任务不执行

5. 项目目录说明
   - src/主程序
   - scripts/启动脚本
   - public/reports/Excel存储
   - 关键文件作用说明

用户可按照README步骤在本地运行项目！

Coze-Commit-Type: user
Coze-User-ID: 3722323274763196
Coze-Conversation-ID: 9894087
This commit is contained in:
user9994793890
2026-07-08 13:22:30 +08:00
parent d856322654
commit bd666687e1
1 changed files with 319 additions and 313 deletions
Download Patch File Download Diff File Expand all files Collapse all files

632
README.md
View File

@@ -1,363 +1,369 @@
# projects
# 订单日报系统 - 本地运行指南
这是一个基于 [Next.js 16](https://nextjs.org) + [shadcn/ui](https://ui.shadcn.com) 的全栈应用项目，由扣子编程 CLI 创建。
这是一个基于 Next.js + TypeScript 的订单日报系统，用于自动生成公交等企业的订单日报。
## 快速开始
## 系统要求
### 启动开发服务器
### 必需软件
1. **Node.js** (版本要求)
- **推荐版本**：Node.js 20+ 或 Node.js 24+
- **最低版本**：Node.js 18.17+
- **下载地址**：https://nodejs.org/
2. **pnpm** (包管理器)
- **安装命令**：
```bash
npm install -g pnpm
```
- **说明**：本项目强制使用pnpm，禁止使用npm或yarn
### 可选软件（用于生产环境）
- **PM2**：用于进程管理和自动重启
```bash
npm install -g pm2
```
## 本地运行步骤
### 1. 安装 Node.js
#### Windows系统
- 访问 https://nodejs.org/
- 下载 LTS 版本（推荐 Node.js 20+）
- 双击安装包，按提示完成安装
- 安装完成后，打开命令提示符验证：
```bash
node --version
npm --version
```
#### macOS系统
- 使用 Homebrew 安装：
```bash
brew install node@20
```
- 或访问官网下载安装包
#### Linux系统 (Ubuntu/Debian)
```bash
# 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# 验证安装
node --version
npm --version
```
### 2. 安装 pnpm
```bash
coze dev
# 全局安装 pnpm
npm install -g pnpm
# 验证安装
pnpm --version
```
启动后，在浏览器中打开 [http://localhost:5000](http://localhost:5000) 查看应用。
开发服务器支持热更新，修改代码后页面会自动刷新。
### 构建生产版本
### 3. 克隆或下载项目
```bash
coze build
# 如果使用 Git
git clone <项目地址>
cd <项目目录>
# 或者直接下载项目压缩包并解压
```
### 启动生产服务器
### 4. 安装项目依赖
```bash
coze start
# 进入项目目录
cd <项目目录>
# 安装所有依赖（必须使用 pnpm）
pnpm install
```
## 项目结构
**安装时间**：首次安装约需5-10分钟，取决于网络速度。
```
src/
├── app/ # Next.js App Router 目录
│ ├── layout.tsx # 根布局组件
│ ├── page.tsx # 首页
│ ├── globals.css # 全局样式（包含 shadcn 主题变量）
│ └── [route]/ # 其他路由页面
├── components/ # React 组件目录
│ └── ui/ # shadcn/ui 基础组件（优先使用）
│ ├── button.tsx
│ ├── card.tsx
│ └── ...
├── lib/ # 工具函数库
│ └── utils.ts # cn() 等工具函数
└── hooks/ # 自定义 React Hooks（可选）
### 5. 配置数据库连接
server/
├── index.ts # 自定义服务器入口
├── tsconfig.json # Server TypeScript 配置
└── dist/ # 编译输出目录（自动生成）
项目已配置好数据库连接，默认连接：
- **地址**：haoslm2.xicp.net:10216
- **数据库**：yltcharge
- **用户名**：root
- **密码**：DsideaL147258369
如果需要修改，编辑 `src/lib/db.ts` 文件。
### 6. 初始化数据库表
首次运行时，需要初始化数据库表：
#### 方式1：通过API初始化（推荐）
启动服务后，访问或调用：
```bash
# 启动服务
pnpm run dev
# 在浏览器访问或使用 curl
# 访问地址：http://localhost:5000/api/init-tables
# 或使用命令：
curl -X POST http://localhost:5000/api/init-tables
```
## 核心开发规范
#### 方式2：手动执行SQL
如果无法访问API，可以手动在数据库执行建表SQL（参考 `src/lib/init-tables.ts`）。
### 1. 组件开发
**优先使用 shadcn/ui 基础组件**
本项目已预装完整的 shadcn/ui 组件库，位于 `src/components/ui/` 目录。开发时应优先使用这些组件作为基础：
```tsx
// ✅ 推荐：使用 shadcn 基础组件
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader } from '@/components/ui/card';
import { Input } from '@/components/ui/input';
export default function MyComponent() {
return (
<Card>
<CardHeader>标题</CardHeader>
<CardContent>
<Input placeholder="输入内容" />
<Button>提交</Button>
</CardContent>
</Card>
);
}
```
**可用的 shadcn 组件清单**
- 表单：`button`, `input`, `textarea`, `select`, `checkbox`, `radio-group`, `switch`, `slider`
- 布局：`card`, `separator`, `tabs`, `accordion`, `collapsible`, `scroll-area`
- 反馈：`alert`, `alert-dialog`, `dialog`, `toast`, `sonner`, `progress`
- 导航：`dropdown-menu`, `menubar`, `navigation-menu`, `context-menu`
- 数据展示：`table`, `avatar`, `badge`, `hover-card`, `tooltip`, `popover`
- 其他：`calendar`, `command`, `carousel`, `resizable`, `sidebar`
详见 `src/components/ui/` 目录下的具体组件实现。
### 2. 路由开发
Next.js 使用文件系统路由，在 `src/app/` 目录下创建文件夹即可添加路由：
### 7. 启动开发服务器
```bash
# 创建新路由 /about
src/app/about/page.tsx
# 创建动态路由 /posts/[id]
src/app/posts/[id]/page.tsx
# 创建路由组（不影响 URL）
src/app/(marketing)/about/page.tsx
# 创建 API 路由
src/app/api/users/route.ts
# 启动开发环境（带热更新）
pnpm run dev
```
**页面组件示例**
```tsx
// src/app/about/page.tsx
import { Button } from '@/components/ui/button';
export const metadata = {
title: '关于我们',
description: '关于页面描述',
};
export default function AboutPage() {
return (
<div>
<h1>关于我们</h1>
<Button>了解更多</Button>
</div>
);
}
**启动成功标志**：
```
✓ Compiled in xxxms
✓ Ready in xxxms
Local: http://localhost:5000
```
**动态路由示例**
### 8. 访问应用
```tsx
// src/app/posts/[id]/page.tsx
export default async function PostPage({
params,
}: {
params: Promise<{ id: string }>;
}) {
const { id } = await params;
打开浏览器，访问：
- **本地地址**：http://localhost:5000
- **功能页面**：
- 配置管理：创建和管理日报配置
- 日报生成：选择配置和时间范围生成日报
- 历史记录：查看和下载已生成的日报
return <div>文章 ID: {id}</div>;
}
```
## 生产环境部署
**API 路由示例**
```tsx
// src/app/api/users/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
return NextResponse.json({ users: [] });
}
export async function POST(request: Request) {
const body = await request.json();
return NextResponse.json({ success: true });
}
```
### 3. 依赖管理
**必须使用 pnpm 管理依赖**
### 1. 构建生产版本
```bash
# ✅ 安装依赖
# 构建优化的生产版本
pnpm run build
```
### 2. 启动生产服务器
#### 方式1：直接启动
```bash
pnpm run start
```
#### 方式2：使用 PM2（推荐）
```bash
# 安装 PM2
npm install -g pm2
# 启动服务
pm2 start scripts/start.sh --name "daily-report"
# 查看状态
pm2 status
# 查看日志
pm2 logs daily-report
# 设置开机自启
pm2 startup
pm2 save
```
### 3. 配置定时任务
项目内置定时任务，每天8:01自动生成日报：
- 定时任务在 `src/server.ts` 中配置
- 使用 node-cron 实现
- 北京时间（UTC+8）
如果需要修改定时任务时间，编辑 `src/server.ts`：
```typescript
// 修改定时任务时间（cron表达式）
cron.schedule('1 8 * * *', async () => {
// 每天8:01执行
console.log('开始生成日报...');
}, {
timezone: "Asia/Shanghai"
});
```
## 常见问题
### 1. pnpm 安装失败
**问题**：`pnpm: command not found`
**解决**：
```bash
# 使用 npm 安装 pnpm
npm install -g pnpm
# 或使用 corepack（Node.js 16.10+）
corepack enable
corepack prepare pnpm@latest --activate
```
### 2. Node.js 版本过低
**问题**：`error: The engine "node" is incompatible`
**解决**：
- 升级 Node.js 到 20+ 版本
- 或修改 `package.json` 中的 engines 配置
### 3. 数据库连接失败
**问题**：`Error: connect ETIMEDOUT` 或 `Error: connect ECONNREFUSED`
**解决**：
1. 检查数据库地址和端口是否正确
2. 检查防火墙是否允许访问
3. 检查数据库用户名和密码
4. 编辑 `src/lib/db.ts` 修改连接配置
### 4. 端口占用
**问题**：`Error: listen EADDRINUSE: address already in use :::5000`
**解决**：
```bash
# Windows
netstat -ano | findstr :5000
taskkill /PID <进程ID> /F
# Linux/macOS
lsof -ti:5000 | xargs kill -9
```
### 5. Excel 文件无法下载
**问题**：点击下载按钮无反应
**解决**：
- 检查 `public/reports/` 目录是否存在
- 检查文件是否成功生成（查看历史记录）
- 浏览器可能拦截下载，检查浏览器设置
### 6. 定时任务不执行
**问题**：8:01没有自动生成日报
**解决**：
1. 确认服务是否持续运行（不要关闭终端）
2. 检查是否有启用的配置（is_active=1）
3. 查看日志是否有错误信息
4. 手动测试定时任务：
```bash
# 访问测试接口（如果有）
curl http://localhost:5000/api/test-cron
```
## 项目目录说明
```
/workspace/projects/
├── src/ ← 主程序目录
│ ├── app/ ← Next.js 应用
│ │ ├── page.tsx ← 主页面（配置、生成、历史）
│ │ ├── api/ ← API 接口
│ │ └── layout.tsx ← 应用布局
│ ├── lib/ ← 核心业务逻辑
│ │ ├── db.ts ← 数据库连接
│ │ ├── report-generator.ts ← 日报生成
│ │ └ init-tables.ts ← 建表脚本
│ │ └ field-mapping.ts ← 字段映射
│ ├── server.ts ← 服务启动（含定时任务）
│ └ components/ ← UI 组件
│ └ hooks/ ← React Hooks
├── scripts/ ← 启动脚本
│ ├── dev.sh ← 开发启动
│ ├── build.sh ← 构建脚本
│ └ start.sh ← 生产启动
├── public/ ← 静态资源
│ └ reports/ ← Excel 文件存储
├── package.json ← 依赖配置
├── tsconfig.json ← TS 配置
├── .coze ← 启动配置
├── AGENTS.md ← 项目说明
└── README.md ← 本文件
```
## 运行命令总结
```bash
# 1. 安装依赖
pnpm install
# ✅ 添加新依赖
pnpm add package-name
# 2. 开发环境启动（带热更新）
pnpm run dev
# 访问：http://localhost:5000
# ✅ 添加开发依赖
pnpm add -D package-name
# 3. 构建生产版本
pnpm run build
# ❌ 禁止使用 npm 或 yarn
# npm install # 错误！
# yarn add # 错误！
# 4. 生产环境启动
pnpm run start
# 5. 代码检查
pnpm run validate
# 6. TypeScript 类型检查
pnpm run ts-check
# 7. 代码格式检查
pnpm run lint
```
项目已配置 `preinstall` 脚本，使用其他包管理器会报错。
## 数据库初始化
### 4. 样式开发
首次运行需要初始化数据库表：
**使用 Tailwind CSS v4**
### 自动创建的表（不修改原表）
本项目使用 Tailwind CSS v4 进行样式开发，并已配置 shadcn 主题变量。
1. **t_daily_report_config** - 配置表
- 存储用户的日报配置
- 包含字段选择、求和字段等
```tsx
// 使用 Tailwind 类名
<div className="flex items-center gap-4 p-4 rounded-lg bg-background">
<Button className="bg-primary text-primary-foreground">
主要按钮
</Button>
</div>
2. **t_daily_report_history** - 历史表
- 记录每次日报生成的历史
- 包含文件路径、统计信息等
// 使用 cn() 工具函数合并类名
import { cn } from '@/lib/utils';
**重要**：原表 `t_equipment_charge_order` 只读取，结构和内容都不会修改。
<div className={cn(
"base-class",
condition && "conditional-class",
className
)}>
内容
</div>
```
## 技术栈说明
**主题变量**
- **Next.js 16**：React全栈框架（App Router模式）
- **React 19**：前端UI库
- **TypeScript 5**：类型安全的JavaScript
- **Tailwind CSS 4**：实用优先的CSS框架
- **shadcn/ui**：基于Radix UI的组件库
- **mysql2**：MySQL数据库驱动
- **node-cron**：定时任务调度器
- **xlsx**：Excel文件生成库
主题变量定义在 `src/app/globals.css` 中，支持亮色/暗色模式：
## 许可和说明
- `--background`, `--foreground`
- `--primary`, `--primary-foreground`
- `--secondary`, `--secondary-foreground`
- `--muted`, `--muted-foreground`
- `--accent`, `--accent-foreground`
- `--destructive`, `--destructive-foreground`
- `--border`, `--input`, `--ring`
- 本项目仅供内部使用
- 数据库连接信息已预配置
- 定时任务使用北京时间（Asia/Shanghai）
- Excel文件存储在 `public/reports/` 目录
### 5. 表单开发
## 获取帮助
推荐使用 `react-hook-form` + `zod` 进行表单开发：
如有问题，请查看：
1. 本README文件的常见问题部分
2. `AGENTS.md` 项目说明文档
3. 检查日志文件（如有）
4. 查看API返回的错误信息
```tsx
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import * as z from 'zod';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
---
const formSchema = z.object({
username: z.string().min(2, '用户名至少 2 个字符'),
email: z.string().email('请输入有效的邮箱'),
});
export default function MyForm() {
const form = useForm({
resolver: zodResolver(formSchema),
defaultValues: { username: '', email: '' },
});
const onSubmit = (data: z.infer<typeof formSchema>) => {
console.log(data);
};
return (
<form onSubmit={form.handleSubmit(onSubmit)}>
<Input {...form.register('username')} />
<Input {...form.register('email')} />
<Button type="submit">提交</Button>
</form>
);
}
```
### 6. 数据获取
**服务端组件（推荐）**
```tsx
// src/app/posts/page.tsx
async function getPosts() {
const res = await fetch('https://api.example.com/posts', {
cache: 'no-store', // 或 'force-cache'
});
return res.json();
}
export default async function PostsPage() {
const posts = await getPosts();
return (
<div>
{posts.map(post => (
<div key={post.id}>{post.title}</div>
))}
</div>
);
}
```
**客户端组件**
```tsx
'use client';
import { useEffect, useState } from 'react';
export default function ClientComponent() {
const [data, setData] = useState(null);
useEffect(() => {
fetch('/api/data')
.then(res => res.json())
.then(setData);
}, []);
return <div>{JSON.stringify(data)}</div>;
}
```
## 常见开发场景
### 添加新页面
1. 在 `src/app/` 下创建文件夹和 `page.tsx`
2. 使用 shadcn 组件构建 UI
3. 根据需要添加 `layout.tsx` 和 `loading.tsx`
### 创建业务组件
1. 在 `src/components/` 下创建组件文件（非 UI 组件）
2. 优先组合使用 `src/components/ui/` 中的基础组件
3. 使用 TypeScript 定义 Props 类型
### 添加全局状态
推荐使用 React Context 或 Zustand：
```tsx
// src/lib/store.ts
import { create } from 'zustand';
interface Store {
count: number;
increment: () => void;
}
export const useStore = create<Store>((set) => ({
count: 0,
increment: () => set((state) => ({ count: state.count + 1 })),
}));
```
### 集成数据库
推荐使用 Prisma 或 Drizzle ORM，在 `src/lib/db.ts` 中配置。
## 技术栈
- **框架**: Next.js 16.1.1 (App Router)
- **UI 组件**: shadcn/ui (基于 Radix UI)
- **样式**: Tailwind CSS v4
- **表单**: React Hook Form + Zod
- **图标**: Lucide React
- **字体**: Geist Sans & Geist Mono
- **包管理器**: pnpm 9+
- **TypeScript**: 5.x
## 参考文档
- [Next.js 官方文档](https://nextjs.org/docs)
- [shadcn/ui 组件文档](https://ui.shadcn.com)
- [Tailwind CSS 文档](https://tailwindcss.com/docs)
- [React Hook Form](https://react-hook-form.com)
## 重要提示
1. **必须使用 pnpm** 作为包管理器
2. **优先使用 shadcn/ui 组件** 而不是从零开发基础组件
3. **遵循 Next.js App Router 规范**，正确区分服务端/客户端组件
4. **使用 TypeScript** 进行类型安全开发
5. **使用 `@/` 路径别名** 导入模块（已配置）
**最后更新时间**：2025-07-08