mirror of
https://github.com/primedigitaltech/market-assistant.git
synced 2026-07-21 15:31:34 +08:00
docs: merge deployment into README, remove DEPLOY_AND_GIT.md
Made-with: Cursor
This commit is contained in:
hub-gif
parent
d8086dfdd5
commit
eceecbffbf
131
README.md
131
README.md
@ -1,14 +1,10 @@
|
||||
# Market-Assistant（低 GI / 京东采集与竞品分析）
|
||||
|
||||
**本目录可作为独立 Git 仓库根目录**：克隆后只需配置 `.env` 与数据区，即可部署并实现当前工作台全部能力（任务、入库、浏览、报告、策略、LLM 等）。代码不依赖仓库外的 `crawler/` 等目录；爬虫副本在 `backend/crawler_copy/jd_pc_search`。
|
||||
**本目录可作为独立 Git 仓库根目录**：克隆后配置 `.env` 与数据区即可运行工作台（任务、入库、浏览、报告、策略、LLM 等）。爬虫副本在 `backend/crawler_copy/jd_pc_search`，不依赖仓库外的其它目录。
|
||||
|
||||
面向「前台事业部」的 Web 工作台：提交京东关键词采集任务、查看流水线产出、**库内分页浏览**已入库的搜索/商详/评价数据、生成竞品分析报告，并支持导出 JSON / CSV / Excel。
|
||||
|
||||
跑批 CSV、`pipeline_runs` 等默认写在**本仓库根目录**下的 `data/JD/`；若数据需放在其它磁盘，可在 `.env` 中设置 **LOW_GI_PROJECT_ROOT** 为绝对路径。
|
||||
|
||||
**环境变量**：全栈**只使用一份** `market_assistant/.env`（模板为 `.env.example`），勿在仓库根或其它子目录再建第二份 `.env`。
|
||||
|
||||
**研发对接**：任务产物、状态与 REST 能力见项目内 **流水线输出说明** 与 **OpenAPI 子集**；部署与 Git 整理见 **docs/DEPLOY_AND_GIT.md**。
|
||||
**研发对接**：任务产物、状态与 REST 能力见 **docs** 下的流水线输出说明与 OpenAPI 子集。
|
||||
|
||||
---
|
||||
|
||||
@ -22,68 +18,99 @@
|
||||
|
||||
---
|
||||
|
||||
## 环境准备
|
||||
## 部署
|
||||
|
||||
- **Python** 3.11+（建议虚拟环境）
|
||||
- **Node.js** 18+（用于前端）
|
||||
- **唯一**环境文件：在本目录（`market_assistant/`）执行：
|
||||
下文**仓库根**指克隆后的项目根目录（含 `backend/`、`frontend/`、`docs/`）。环境变量**只使用仓库根下一份** `.env`（模板为 `.env.example`），勿在 `backend/` 等子目录再建第二份。
|
||||
|
||||
### 环境变量（`.env`）
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| 仓库根 `.env` | 运行时配置（勿提交 Git）；从 `.env.example` 复制 |
|
||||
| `.env.example` | 模板，可随仓库分发 |
|
||||
|
||||
Django（`backend/config/settings.py`）与 `backend/crawler_copy/jd_pc_search/AI_crawler.py` 均从**仓库根**的 `.env` 加载。
|
||||
|
||||
**首次编辑建议：**
|
||||
|
||||
1. 复制：`cp .env.example .env`（Windows：`copy .env.example .env`）。
|
||||
2. 填写 **`DJANGO_SECRET_KEY`**；生产将 **`DJANGO_DEBUG`** 设为 `False`，并配置 **`DJANGO_ALLOWED_HOSTS`**、**`CORS_ALLOWED_ORIGINS`**、**`CSRF_TRUSTED_ORIGINS`**（域名带协议，如 `https://app.example.com`）。
|
||||
3. **`LOW_GI_PROJECT_ROOT`（可选）**：不设置时，跑批数据默认在仓库根 **`./data/JD/`**（启动 Django 时会创建）；单独数据盘则设为可写绝对路径，数据落在其下 `data/JD/...`。
|
||||
4. 使用配料图识别、报告/策略 LLM 时：填写 **`OPENAI_*`** 或 **`LLM_*`**。
|
||||
|
||||
### 运行环境与依赖
|
||||
|
||||
| 层级 | 要求 | 说明 |
|
||||
|------|------|------|
|
||||
| 后端 | Python **3.11+** | 建议虚拟环境；依赖见 `backend/requirements.txt` |
|
||||
| 前端 | **Node.js 18+** | 生产构建建议 `npm ci`（需 `package-lock.json`） |
|
||||
| 流水线 / 采集 | **Node.js**；按需 **Playwright** | 调用 `backend/crawler_copy/jd_pc_search` 下脚本与子进程 |
|
||||
| 数据目录 | 磁盘可写 | 默认 `./data/JD/`；或 `LOW_GI_PROJECT_ROOT` |
|
||||
| Cookie | 本地文件（默认不入库） | `backend/crawler_copy/jd_pc_search/common/jd_cookie.txt`，或按工作台接口配置 |
|
||||
|
||||
### 首次安装（后端）
|
||||
|
||||
在仓库根进入 `backend/`，创建虚拟环境、安装依赖并迁移：
|
||||
|
||||
```bash
|
||||
copy .env.example .env
|
||||
```
|
||||
|
||||
编辑 `.env`，至少设置：
|
||||
|
||||
- **DJANGO_SECRET_KEY**；生产环境将 **DJANGO_DEBUG** 设为 False，并配置 **ALLOWED_HOSTS** 与 CORS/CSRF。
|
||||
- **LOW_GI_PROJECT_ROOT**（可选）：不填则数据写在仓库根下 `data/JD/`；单独数据盘时再填绝对路径。
|
||||
- 若使用配料识别、报告/策略 LLM：在同一文件填写 **OPENAI_*** 或 **LLM_***（与 `AI_crawler` 共用，无需另建 `.env`）。
|
||||
|
||||
---
|
||||
|
||||
## 启动后端
|
||||
|
||||
在后端子目录下执行：
|
||||
|
||||
```bash
|
||||
cd market_assistant/backend
|
||||
|
||||
# 安装依赖（建议在 venv 中）
|
||||
cd backend
|
||||
python -m venv .venv
|
||||
# Windows: .venv\Scripts\activate
|
||||
# Linux/macOS: source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 数据库迁移
|
||||
python manage.py migrate
|
||||
|
||||
# 开发服务（默认 http://127.0.0.1:8000）
|
||||
python manage.py runserver
|
||||
```
|
||||
|
||||
管理后台（可选）：创建超级用户后访问 Django 管理地址。
|
||||
若要跑采集流水线：在本机安装 Node / Playwright（与现有开发环境一致），并准备好 Cookie。
|
||||
|
||||
---
|
||||
### 开发环境（前后端联调）
|
||||
|
||||
## 启动前端
|
||||
| 顺序 | 目录 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 1 | `backend/` | `python manage.py runserver` | 默认 **http://127.0.0.1:8000**，REST 在 **`/api`** |
|
||||
| 2 | `frontend/` | `npm install`（首次）、`npm run dev` | 默认 **http://127.0.0.1:5173** |
|
||||
|
||||
在前端子目录下执行：
|
||||
**须先启动后端，再启动前端。** `frontend/vite.config.js` 将 **`/api`** 代理到 `http://127.0.0.1:8000`，浏览器只访问 Vite 地址即可。
|
||||
|
||||
其它前端命令：`npm run build`（生产构建）、`npm run preview`（预览构建结果）。
|
||||
|
||||
可选：`python manage.py createsuperuser` 后访问 **http://127.0.0.1:8000/admin/**。
|
||||
|
||||
### 生产环境（构建与反向代理）
|
||||
|
||||
**后端**
|
||||
|
||||
1. 与开发相同 Python 版本，在 `backend/` 执行安装依赖与 `migrate`。
|
||||
2. 使用 **Gunicorn**（或 uWSGI 等）托管 WSGI，示例：
|
||||
|
||||
```bash
|
||||
cd market_assistant/frontend
|
||||
|
||||
# 首次安装依赖
|
||||
npm install
|
||||
|
||||
# 开发模式（默认 http://127.0.0.1:5173）
|
||||
npm run dev
|
||||
cd backend
|
||||
gunicorn config.wsgi:application --bind 127.0.0.1:8000 --workers 3
|
||||
```
|
||||
|
||||
浏览器打开本地开发地址。开发环境下，前端将 **API** 代理到后端端口，因此需**先启动后端**，再启动前端。
|
||||
3. 用 **Nginx**（或其它网关）将 **`/api`**（及如需的 `admin`）反代到上述进程。
|
||||
4. `.env` 中 `ALLOWED_HOSTS`、CORS、CSRF 与实际上线域名、协议一致。
|
||||
|
||||
其他脚本：
|
||||
**前端**
|
||||
|
||||
```bash
|
||||
npm run build # 生产构建
|
||||
npm run preview # 本地预览构建结果
|
||||
cd frontend
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
|
||||
将 **`dist/`** 作为静态站点根目录托管。**推荐同源**：同域下静态资源 + `location /api/` 反代到 Gunicorn。若前后端不同域，配置好 CORS/CSRF，并注意 HTTPS 混合内容等问题。
|
||||
|
||||
生产**不使用** Vite 开发服务；`vite.config.js` 里的 `proxy` 仅在 `npm run dev` 时生效。
|
||||
|
||||
### 部署自检清单
|
||||
|
||||
- [ ] 已执行 `python manage.py migrate`
|
||||
- [ ] 生产环境已更换密钥，`DEBUG=False`
|
||||
- [ ] `ALLOWED_HOSTS` / `CORS_*` / `CSRF_*` 与真实访问地址一致
|
||||
- [ ] `data/JD/` 或 `LOW_GI_PROJECT_ROOT` 对应目录可写
|
||||
- [ ] 需要流水线时：Node、Playwright、Cookie 已就绪
|
||||
|
||||
---
|
||||
|
||||
## 常用功能说明
|
||||
@ -101,15 +128,13 @@ npm run preview # 本地预览构建结果
|
||||
|
||||
## API 前缀
|
||||
|
||||
开发时 REST 接口默认在后端根地址下的 **/api**；前端通过同源代理访问即可。
|
||||
开发时 REST 默认在后端根地址下的 **`/api`**；本地通过 Vite 代理访问即可。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
均在项目 **docs** 目录下，主要包括：项目进展与里程碑、流水线输出说明、演示与脱敏、工程说明等。
|
||||
|
||||
**部署、Git 仓库整理、单 `.env` 约定**：见 [docs/DEPLOY_AND_GIT.md](docs/DEPLOY_AND_GIT.md)。
|
||||
均在 **docs** 目录：项目进展与里程碑、流水线输出说明、演示与脱敏、工程说明、OpenAPI 等。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -1,101 +0,0 @@
|
||||
# 部署与 Git 仓库整理
|
||||
|
||||
## 1. 环境变量：仅一份 `.env`
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `market_assistant/.env` | 本地与服务器上的**唯一**配置（密钥、路径、Django、LLM） |
|
||||
| `market_assistant/.env.example` | 模板，可提交仓库 |
|
||||
|
||||
已移除「仓库根目录 `.env`」与「`backend/.env`」第二加载源；Django 与 `crawler_copy/jd_pc_search/AI_crawler.py` 均从 `market_assistant/.env` 读取（`AI_crawler` 在导入时先加载该文件再解析 `LOW_GI_PROJECT_ROOT`）。
|
||||
|
||||
部署到新机器：
|
||||
|
||||
1. 复制 `market_assistant/.env.example` → `market_assistant/.env`
|
||||
2. **可选**：设置 `LOW_GI_PROJECT_ROOT` 为单独数据盘的绝对路径；不设置时默认为**本仓库根目录**，数据写在 `./data/JD/`（启动 Django 时会自动创建该目录）
|
||||
3. 设置 `DJANGO_SECRET_KEY`、`DJANGO_DEBUG=False`、生产域名下的 `DJANGO_ALLOWED_HOSTS` / `CORS_*` / `CSRF_*`
|
||||
4. 若使用 LLM，填写 `OPENAI_*` 或 `LLM_*`
|
||||
|
||||
## 2. 功能是否只需本目录？
|
||||
|
||||
**是。** `market_assistant` 内含：
|
||||
|
||||
- Django API、流水线任务、入库与导出
|
||||
- 前端 Vue 工作台
|
||||
- 京东采集脚本副本 `backend/crawler_copy/jd_pc_search`（含 Node/Playwright 子进程调用）
|
||||
|
||||
**不要求**仓库外仍存在旧的 `crawler/jd_pc_search`。
|
||||
|
||||
**运行时另需**（部分不在 Git 中）：
|
||||
|
||||
- 默认可写目录为仓库根下 `data/JD/`（`.gitignore` 已忽略）；若配置了 `LOW_GI_PROJECT_ROOT` 则数据在该路径下
|
||||
- 按任务配置放置 Cookie（路径须在有效数据根之下，如 `common/jd_cookie.txt`）
|
||||
- 本机已装 Node、流水线所需的 Playwright 等（与现有一致）
|
||||
|
||||
## 3. 远程 Git 只维护 `market_assistant`（推荐两种做法）
|
||||
|
||||
> **先备份仓库**，再在副本上操作；改写历史后需与团队约定 **`git push --force`**。
|
||||
|
||||
### 方案 A：保留历史，把子目录提成仓库根（git filter-repo）
|
||||
|
||||
适用于「当前仓库在上一级 `Low GI/`，只想提交 `market_assistant/` 里的内容且路径变为仓库根」。
|
||||
|
||||
1. 安装 [git-filter-repo](https://github.com/newren/git-filter-repo)（需单独安装，不是 Git 自带）。
|
||||
2. 在**原仓库克隆的副本**中执行：
|
||||
|
||||
```bash
|
||||
cd /path/to/Low-GI-repo-copy
|
||||
git filter-repo --path market_assistant/ --path-rename market_assistant/:
|
||||
```
|
||||
|
||||
3. 此时仓库根目录即为原 `market_assistant` 下的 `backend/`、`frontend/`、`docs/` 等。
|
||||
4. 将 `origin` 改为新远程或清空原远程后强制推送：
|
||||
|
||||
```bash
|
||||
git remote add origin <你的新仓库 URL>
|
||||
git branch -M main
|
||||
git push -u origin main --force
|
||||
```
|
||||
|
||||
5. 旧远程若废弃，在 Git 平台将旧库归档或删除，避免误用。
|
||||
|
||||
### 方案 B：新仓库，不保留旧历史
|
||||
|
||||
适用于「从零起一个干净远程，只装当前代码」。
|
||||
|
||||
```bash
|
||||
cd market_assistant
|
||||
git init
|
||||
git add .
|
||||
git commit -m "chore: initial standalone market_assistant"
|
||||
git remote add origin <新仓库 URL>
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
之后本地开发只在 `market_assistant` 目录内 `git pull` / `git push`。
|
||||
|
||||
### 拆库后目录约定
|
||||
|
||||
- 克隆下来的**仓库根** = 现在的 `market_assistant`（含 `backend/`、`frontend/`、`docs/`）。
|
||||
- 文档中的路径仍写 `market_assistant/.env` 时，在「已拆库」情形下指**仓库根目录下的** `.env`（即 `.env` 在 clone 下来的根上）。
|
||||
|
||||
### 已从跟踪中移除误提交文件（旧 monorepo 根目录上执行）
|
||||
|
||||
若仍暂时保留大仓库，可在**原根目录**执行：
|
||||
|
||||
```bash
|
||||
git rm -r --cached venv/ 2>/dev/null || true
|
||||
git rm -r --cached data/ 2>/dev/null || true
|
||||
git rm -r --cached .idea/ 2>/dev/null || true
|
||||
git rm --cached .env 2>/dev/null || true
|
||||
```
|
||||
|
||||
## 4. 生产构建（简要）
|
||||
|
||||
- **后端**：`pip install -r backend/requirements.txt`，`migrate`，用 gunicorn/uwsgi 等托管 WSGI，前面 Nginx 反代。
|
||||
- **前端**：`cd frontend && npm ci && npm run build`，将 `dist/` 由 Nginx 托管静态资源，并把 `/api` 反代到 Django；同时把生产环境的 CORS/CSRF 与 `vite.config.js` 开发代理区分配置（生产一般同源或显式写 API 域名）。
|
||||
|
||||
## 5. 与 `LOW_GI_PROJECT_ROOT` 的关系
|
||||
|
||||
流水线 CSV、跑批目录默认写在 `LOW_GI_PROJECT_ROOT/data/JD/...`。该路径**可以**在服务器上位于 Web 代码库之外（例如单独数据盘），只要在 `.env` 中指向正确绝对路径即可。
|
||||
@ -130,7 +130,7 @@
|
||||
| 序号 | 任务 | 产出 | 建议完成日 |
|
||||
|------|------|------|------------|
|
||||
| 4.1 | 权限、密钥、日志与审计（按公司规范） | 配置说明 | **2026-06-25** |
|
||||
| 4.2 | 部署文档（Docker/主机二选一） | README 或单独部署说明 | **2026-06-27** |
|
||||
| 4.2 | 部署文档（Docker/主机二选一） | README「部署」章节 | **2026-06-27** |
|
||||
| 4.3 | 前台事业部试用反馈一轮 | 问题清单 + 下一迭代 backlog | **2026-06-30** |
|
||||
|
||||
**阶段 4 里程碑 Git**：**push**；可选 `v1.0-internal-release`。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user