diff --git a/README.md b/README.md index 6813bd6..b08a492 100644 --- a/README.md +++ b/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 等。 --- diff --git a/docs/DEPLOY_AND_GIT.md b/docs/DEPLOY_AND_GIT.md deleted file mode 100644 index 78533ba..0000000 --- a/docs/DEPLOY_AND_GIT.md +++ /dev/null @@ -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` 中指向正确绝对路径即可。 diff --git a/docs/Market-Assistant-项目进展与里程碑.md b/docs/Market-Assistant-项目进展与里程碑.md index 7da734c..5a774b5 100644 --- a/docs/Market-Assistant-项目进展与里程碑.md +++ b/docs/Market-Assistant-项目进展与里程碑.md @@ -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`。