beige/客户交付前完整审核报告.md

# Clover 客户交付前完整审核报告

审核日期：2026-06-26

审核对象：`/Users/qiyu/Documents/企业培训项目/万牛会L1准备/北哥小红书产品/Clover`

审核口径：以当前工作区为准，包含未提交修改和未跟踪新增文件。本文档只记录审核结论与整改方案，不包含真实密钥值。

## 一、总审核结论

当前项目**不建议直接交付客户生产使用**。

原因不是单点 bug，而是交付前仍存在安全、部署、测试、业务链路一致性、文件路径、版本冻结和文档可信度等多类风险。前端生产构建可以通过，后端代码可编译，但这只能说明项目有基本可构建性，不能证明已经达到客户可稳定使用的交付标准。

交付前必须先处理 P0 问题，再处理 P1 问题。P2 问题可以排期，但至少要在交付说明中明确边界和已知风险。

## 二、已执行的只读检查与结果

| 检查项 | 命令/方式 | 结果 |
|---|---|---|
| 前端生产构建 | `npm run build` | 通过 |
| 前端 lint | `npm run lint` | 失败，进入 ESLint 初始化交互，不能作为一键质量检查 |
| 后端测试 | `python3 -m pytest -q` | 失败：缺 `celery` 依赖，且临时测试文件导入阶段尝试写 `/app` |
| 后端语法编译 | `python3 -m compileall -q app` | 通过 |
| 前端依赖安全审计 | `npm audit --audit-level=high --omit=dev` | 失败：Next.js critical，PostCSS moderate |
| Git 工作区 | `git status --short` / `git diff --stat` | 43 个已修改文件，另有多批未跟踪文件、截图、验证输出 |
| 项目体积 | `du -sh` | 项目约 439M，`frontend/node_modules` 约 328M，`.next` 约 74M |
| 代码入口核对 | FastAPI 路由、Next 页面、Celery worker、OpenAPI、Docker 配置 | 发现多处实现/文档/类型不一致 |

## 三、P0 必须修复问题

### P0-1 明文环境文件和密钥泄露风险

**问题**

项目目录内存在多份 `.env`、备份环境文件、测试环境文件，包含第三方 API Key、JWT/FERNET、数据库密码等敏感配置。虽然这些文件未被 Git 跟踪，但如果按目录整体打包交付给客户，会直接泄露。

涉及文件类型包括：

- `.env`
- `.env.bak`
- `backend/.env`
- `backend/.env.bak.*`
- `frontend/.env.local`
- `test/.env`

**风险**

- 第三方模型账号被滥用，产生费用。
- 客户或外部人员可伪造 JWT 或解密历史 API Key 密文。
- 数据库、Redis、MongoDB 凭据泄露。
- 客户交付包中出现开发方内部密钥，属于严重交付事故。

**修改方案**

1. 交付包只保留 `.env.example`，删除所有真实 `.env*`、备份 env、测试 env。
2. 立即轮换已经出现在本地文件里的第三方 API Key、JWT_SECRET、FERNET_KEY、数据库密码。
3. 增加交付打包脚本，默认排除 `.env*`、`*.bak*`、`test/.env`。
4. 在 README 中写清楚客户需要自行填写哪些环境变量。

### P0-2 Next.js 生产依赖存在 critical 漏洞

**问题**

`npm audit --audit-level=high --omit=dev` 报告 `next@14.2.0` 存在 critical 级漏洞，PostCSS 存在 moderate 漏洞。

**风险**

客户部署的是 Web 应用，Next.js 相关漏洞可能涉及缓存污染、授权绕过、DoS、SSRF、XSS 等风险。即使某些漏洞只在特定配置下触发，也不应带 critical 依赖交付。

**修改方案**

1. 升级 `next` 到审计建议的修复版本，例如 `14.2.35` 或更高兼容版本。
2. 同步升级 `eslint-config-next`，避免版本错配。
3. 重新执行 `npm install` 更新 `package-lock.json`。
4. 重新验证 `npm run build`、`npm run lint`、`npm audit --audit-level=high --omit=dev`。

### P0-3 Docker 部署仍是开发形态

**问题**

`backend/docker-compose.yml` 中 API 使用：

- 源码目录挂载：`.:/app`
- `uvicorn --reload`
- MySQL/Redis/MongoDB 端口直接映射到宿主机

这更像本地开发配置，不是客户生产部署配置。

**风险**

- `--reload` 增加生产不稳定性和资源开销。
- 源码挂载导致容器内容和宿主机状态耦合。
- 数据库、Redis、MongoDB 暴露到宿主机端口，若服务器安全组配置不当，可能被外部访问。

**修改方案**

1. 拆分 `docker-compose.prod.yml`。
2. 生产 API 命令改为不带 `--reload` 的固定进程。
3. 生产环境不挂载源码目录，只挂载上传目录和持久化数据卷。
4. MySQL/Redis/MongoDB 不暴露公网端口，只在 Docker 内部网络访问。
5. 增加生产部署文档，明确开发 compose 与生产 compose 的区别。

### P0-4 CORS 生产未收口

**问题**

`backend/main.py` 中 CORS 仍为 `allow_origins=["*"]`。

**风险**

任意来源页面都可以向后端发起跨域请求。即使接口需要 JWT，这仍会扩大攻击面，不符合客户生产交付标准。

**修改方案**

1. 增加 `CORS_ORIGINS` 环境变量。
2. 生产环境只允许客户前端域名。
3. 开发环境可保留 localhost 白名单。
4. `APP_ENV=production` 时禁止 `*`。

### P0-5 测试不可一键运行

**问题**

后端 `python3 -m pytest -q` 失败：

- 当前环境缺 `celery`。
- `backend/test_color_compare.py` 在导入阶段创建 `/app/...`，触发权限错误。
- 顶层临时验证脚本会被 pytest 自动收集。

前端 `npm run lint` 失败：

- 进入 Next.js ESLint 初始化交互，不是非交互式检查。

**风险**

交付前无法用自动化测试证明项目状态稳定。客户或接手工程师也无法复现质量检查。

**修改方案**

1. 后端测试固定用 Docker test profile 或 `.venv`，并写入 README。
2. 临时验证脚本移出 pytest 自动收集范围，或改名不以 `test_` 开头。
3. 所有测试不得在 import 阶段写文件。
4. 前端补 `.eslintrc` 或 `eslint.config.*`，让 `npm run lint` 非交互式执行。
5. 增加统一验收命令，例如 `make verify` 或 `scripts/verify.sh`。

### P0-6 默认账号和默认密码风险

**问题**

`backend/scripts/seed_data.py` 内置 admin/supervisor/operator 三类账号，并使用同一默认密码。

**风险**

如果客户生产环境直接使用 seed 数据且未改密，任何知道交付包的人都可能登录系统。

**修改方案**

1. seed 仅用于初始化，不得作为生产长期账号配置。
2. 首次登录强制改密。
3. 生产交付说明中明确默认账号仅用于首次进入。
4. 客户验收后删除或禁用默认密码账号。

## 四、P1 交付前应修复问题

### P1-1 当前工作区不是干净交付版本

**问题**

当前 Git 工作区存在 43 个已修改文件，并有大量未跟踪文件，包括新增组件、截图、验证输出、计划文档等。

**风险**

无法判断客户拿到的是稳定版本、实验版本还是半成品版本。后续问题排查也没有明确基线。

**修改方案**

1. 先确定交付基准 commit。
2. 将要交付的代码整理成干净分支。
3. 删除或排除截图、验证输出、缓存文件、临时计划文档。
4. 打交付 tag，例如 `delivery-beige-xhs-v1.0.0`。

### P1-2 文案/图片多选语义与真实处理不一致

**问题**

前端文案页允许多选，图片页也允许多选；后端选择接口只是把当前候选置为 `is_selected=True`，不会取消同任务下旧选择。生成图片时实际只取第一条文案作为语境；审核队列也只展示第一条选中文案和第一张选中图。

**风险**

客户会以为自己选择了多条文案/多组图片，但生成、审核、打包结果不一定按选择生效。最终交付内容可能文图不匹配。

**修改方案**

1. 明确产品语义：每套 A/B/C 选择一条文案和一组图片，或明确只允许单选。
2. 如果保留三套，后端选择接口应按 `task_id + strategy` 清理旧选择。
3. 生图、审核、打包全部按 strategy 配对。
4. 前端按钮文案和 UI 状态同步改为“每套选择”。

### P1-3 文件路径存储和读取不稳定

**问题**

项目里同时存在：

- 产品图存容器绝对路径。
- 生成图用 `UPLOAD_BASE_PATH` 相对路径。
- 静态服务挂载 `/uploads`。
- 打包任务用 URL 反推本地路径读取图片。

**风险**

本地运行、Docker 运行、客户服务器部署时路径根目录不同，可能出现图片前端能看但 worker 读不到、worker 写了但前端访问不到、打包 zip 里缺图。

**修改方案**

1. 数据库只保存相对对象路径，例如 `products/{workspace_id}/{product_id}/{file}`。
2. 后端统一用 `UPLOAD_ABS_ROOT` 拼本地绝对路径。
3. 前端 URL 统一由后端转换成 `/uploads/...`。
4. 打包任务不得从 URL 反推路径，应使用统一路径解析函数。

### P1-4 交付包状态查询接口有副作用

**问题**

`GET /delivery-packages/{package_id}/download` 查询状态时，如果状态是 `ready`，会改成 `downloaded`。

**风险**

前端轮询或用户刷新页面就会改变业务状态。客户看到的状态可能不是实际下载行为。

**修改方案**

1. 状态查询接口只读，不修改状态。
2. 文件真正开始下载或下载成功后再标记 `downloaded`。
3. 如果无法检测下载成功，至少单独提供“确认已下载”接口。

### P1-5 任务创建产品校验不完整

**问题**

当 `need_product_image=True` 时会校验产品存在和产品图；但如果关闭产品入镜，可以创建指向不存在产品的任务。

**风险**

后续 worker 构建产品信息时可能失败，或生成质量不可控。

**修改方案**

1. 无论是否产品入镜，都校验 `product_id` 存在、属于当前 workspace、处于 active。
2. `need_product_image` 只额外控制是否要求产品参考图。

### P1-6 裂变源文案可能直接使用 JSON 字符串

**问题**

`TextCandidate.content` 存储的是 JSON 字符串；裂变服务读取源文案时直接返回该字段，没有稳定解析出纯正文。

**风险**

裂变 prompt 可能拿到 JSON 原文，影响生成质量和输出格式。

**修改方案**

1. 裂变读取源文案时先解析 JSON。
2. 拼接 `title/content/tags` 为纯发布文案。
3. 解析失败才回退原始文本。

### P1-7 OpenAPI、前端 DTO、后端实现不一致

**问题**

存在多处契约分叉，例如：

- `SwitchWorkspaceResponse` 前端声明有 `role`，后端实际不返回。
- 导出接口直接返回数组或 CSV，不走统一 `{ code, data }` 包络。
- README 和 OpenAPI 对已有功能描述滞后。

**风险**

后续开发者按文档接入会出错；前端类型不能真实约束后端行为。

**修改方案**

1. 以实际 FastAPI 路由重新梳理 OpenAPI。
2. 前端 DTO 与后端响应逐项对齐。
3. 导出类接口如果故意不走包络，应在文档里明确标注。
4. 增加契约测试，至少覆盖前端已调用接口。

### P1-8 前端 SSE 和 API 基础地址部署边界不清

**问题**

前端 API 默认相对路径，Next rewrite 默认指向 `http://localhost:8000`；SSE 另有 `NEXT_PUBLIC_SSE_BASE_URL`，注释说明必须绕过 Next rewrite。

**风险**

客户部署时如果只配置 API 地址而没配置 SSE 地址，实时进度可能失效。跨域时还会叠加 CORS 和网络配置问题。

**修改方案**

1. 生产 `.env.example` 明确列出 `NEXT_PUBLIC_API_BASE_URL` 和 `NEXT_PUBLIC_SSE_BASE_URL`。
2. 部署文档给出同域反代和跨域直连两种配置。
3. 增加 SSE 连通性验收步骤。

## 五、P2 建议修复问题

### P2-1 README 和真实项目状态错位

**问题**

后端 README 仍写 migration 到 004，但实际已有 021；前端 README 写“五屏骨架”，实际已有 dashboard、board、history、fission、settings 等页面。

**风险**

客户或接手人员按 README 操作会误判项目状态。

**修改方案**

1. 重写根 README、前端 README、后端 README。
2. 以“客户如何启动、如何配置、如何验收”为中心，而不是开发历史。
3. 加入故障排查章节。

### P2-2 交付目录过重且包含临时产物

**问题**

项目约 439M，其中 `frontend/node_modules` 约 328M，`.next` 约 74M；目录中还有大量截图、缓存、验证输出。

**风险**

交付包臃肿，且容易夹带开发过程文件、客户素材或内部验证信息。

**修改方案**

1. 交付源码包排除 `node_modules`、`.next`、`__pycache__`、`.pytest_cache`、截图、verify_output。
2. 提供 `package-lock.json` 和 `requirements.txt`，由客户环境安装依赖。
3. 单独准备必要的样例素材，不混入开发截图。

### P2-3 fallback 结果可能掩盖真实失败

**问题**

视觉分析、标杆分析、裂变等模块有 fallback 逻辑。fallback 能避免空结果，但客户可能无法分辨结果是模型真实分析还是兜底模板。

**风险**

客户把兜底结果当真实 AI 结果使用，影响内容质量。

**修改方案**

1. 所有 fallback 结果在 UI 明确标注“兜底生成，需要人工复核”。
2. 交付包中保留来源字段。
3. 日志和任务详情中保存失败原因。

### P2-4 Python 依赖缺少安全审计

**问题**

本地没有 `pip_audit`，因此没有完成 Python 依赖漏洞审计。

**风险**

后端依赖可能存在已知漏洞但未被发现。

**修改方案**

1. 在 CI 或 Docker test profile 中安装并执行 `pip-audit -r requirements.txt`。
2. 将结果纳入交付前验收。

## 六、建议整改顺序

1. 先冻结交付分支，清理工作区，明确客户要拿到哪个版本。
2. 删除真实环境文件并轮换密钥。
3. 升级 Next.js 并通过 `npm audit`。
4. 拆生产部署配置，收口 CORS 和端口暴露。
5. 修测试体系，让前后端检查可一键运行。
6. 修文案/图片选择、审核、打包之间的语义一致性。
7. 修统一文件路径策略。
8. 重写客户交付 README 和验收清单。
9. 跑完整端到端验收。

## 七、最终交付前 Checklist

交付前必须逐项确认：

- [ ] 交付包不包含任何真实 `.env*`、备份 env、测试 env。
- [ ] 所有已泄露风险的 Key 和密码已轮换。
- [ ] `npm run build` 通过。
- [ ] `npm run lint` 非交互式通过。
- [ ] `npm audit --audit-level=high --omit=dev` 无 high/critical。
- [ ] `python3 -m pytest -q` 在标准环境通过。
- [ ] 后端依赖完成漏洞审计。
- [ ] 生产 Docker 配置不使用 `--reload`。
- [ ] 数据库、Redis、MongoDB 不对公网暴露。
- [ ] CORS 仅允许客户前端域名。
- [ ] 默认账号首次登录必须改密。
- [ ] 产品图上传、生成图展示、打包下载在生产部署环境跑通。
- [ ] SSE 实时进度在生产域名下跑通。
- [ ] 文案选择、图片选择、审核、打包结果一致。
- [ ] 客户 README 与实际启动方式一致。
- [ ] Git 工作区干净，并打交付 tag。

## 八、最终判断

本轮整改后，代码层 P0/P1 阻断项已完成核销，可以进入客户交付前最终验收阶段。

正式交付仍必须满足：

1. 不直接整目录拷贝，必须使用干净交付包并排除真实 `.env*`、`node_modules`、`.next`、验证产物和截图。
2. 已暴露风险的 Key、默认密码、数据库密码全部轮换。
3. 用客户部署方式完成一次真实端到端验收。

## 九、本轮修复核销记录（2026-06-26）

本轮已按“B 类功能 bug → A 类交付卫生 → C 类安全收口”的顺序完成整改，并做了交叉验证。

### 已核销

- `apiports` 图片编辑备份已改为 `/chat/completions` 多模态参考图路径；`codeproxy` 保持 `/images/edits`。
- A/B/C 三套内容已按 `strategy` 绑定文案和图片，生图不再复用第一条文案。
- 提交审核前强制校验 A/B/C 每套都有已选文案，并且每套选满 `task.image_count` 张图片。
- 审核队列新增 `selected_sets`，前端可按 A/B/C 展示，同时保留旧字段兼容。
- 下载状态 GET 和文件下载 GET 均已改为只读；前端下载成功后显式调用 POST 标记 `downloaded`。
- 创建任务无论是否产品入镜，都会校验产品存在且属于当前 workspace。
- 裂变源文案会解析 JSON 候选并提取标题/正文/卖点，不再把整段 JSON 字符串当源文案。
- 工作区切换响应补齐 `role` 字段。
- 标杆 fallback 结果已在 API 和前端显式标注，任务创建不再选用 fallback 标杆。
- `/uploads` 静态挂载统一使用 `UPLOAD_ABS_ROOT`，避免写盘目录和访问目录不一致。
- 新增 `.env.example`、`backend/.env.example`、`frontend/.env.example`。
- 新增 `.dockerignore`、`backend/.dockerignore`、`frontend/.dockerignore`，并扩展 `.gitignore` 排除验证产物和截图。
- 新增 `docker-compose.prod.yml`，生产启动不挂载源码、不使用 `--reload`，数据库/Redis/Mongo 不暴露宿主端口。
- 新增根目录 `README.md`，更新前后端 README，使迁移版本、页面数量、SSE/API 配置说明与当前代码一致。
- 新增 `backend/pytest.ini`，后端 pytest 只收集 `backend/tests`，避免临时验证脚本被误收集。
- 前端 lint 已从交互式 `next lint` 改为 ESLint 9 flat config，可一键运行。
- Next 已升级到 `16.2.9`，并用 `overrides` 将依赖树中的 `postcss` 收到安全版本。
- 生产 CORS 已从硬编码 `*` 改为 `CORS_ALLOW_ORIGINS`，生产环境会过滤通配符。
- 默认种子密码 `Clover2026!` 在生产登录中被拒绝；生产执行 seed 必须显式设置非默认 `CLOVER_SEED_PASSWORD`。

### 最终验证命令

- `cd backend && python3 -m compileall -q app tests`：通过。
- `cd backend && python3 -m pytest`：通过，`113 passed`。
- `cd frontend && npm run lint`：通过，0 error，仍有 12 个 warning。
- `cd frontend && npm run build`：通过，Next `16.2.9`，webpack 构建。
- `cd frontend && npm audit --omit=dev`：通过，`found 0 vulnerabilities`。
- `docker compose -f docker-compose.prod.yml --env-file .env.example config`：通过。

### 仍需交付前人工确认

- 真实 `.env` 和历史 `.env.bak` 文件仍在本地工作区，未做破坏性删除；交付包必须排除，且已暴露风险的 Key/密码必须轮换。
- 当前 git 工作区仍有大量既有改动和未跟踪文件；正式交付前需要冻结版本、确认 diff、打交付 tag。
- Python 依赖尚未执行 `pip-audit`，因为本地未安装该工具；建议在 CI 或交付镜像中补跑。
- 尚未在真实客户域名、真实数据库、真实 Redis/Mongo、真实 AI provider 恢复后跑完整端到端验收。