Stev_Wang
6096568621
- 新增双项目整合可行性评估 V0.1 rev.2：覆盖度矩阵、方案对比、目标架构、工作量/TCO、风险与决策清单 - 新增 dewu/sucaigongfang 两份调研报告（内部资料，平台敏感值已脱敏） - 新增技术栈与架构定稿 V1.0：Node 24.15.0 / pnpm 11.4.0 / Prisma 7.10.1 / PostgreSQL 18 / Redis 7 - 更新 README 文档索引与仓库结构
1015 lines
52 KiB
Markdown
1015 lines
52 KiB
Markdown
# 平台电商素材生产平台 · 技术栈与架构定稿
|
||
|
||
> **文档类型**：技术栈与架构设计（定稿）
|
||
> **版本**：V1.0 | **状态**：已定稿（评审通过后进入 M0） | **日期**：2026-10-30
|
||
> **适用范围**：统一 WEB 平台（选品 → 原始物料 → 图片/视频生产 → 命名 → 提审 → 投放配置）
|
||
> **输入依据**：`docs/PRD/平台电商素材生产平台_PRD_V0.1.md`、两份参考项目调研报告、`docs/评估/平台电商素材生产平台_整合可行性评估_V0.1.md`
|
||
> **环境基线（已在本机核实）**：macOS arm64、Node **v24.15.0**、pnpm **11.4.0**、PostgreSQL **18.4**（Docker，5432）、Redis **7.4.9**（Docker，6379）
|
||
> **密级**：内部；本文不含平台签名盐、账号、密钥等敏感值。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
0. 定稿结论（一页纸）
|
||
1. 决策依据与约束
|
||
2. 技术栈总表（版本锁定）
|
||
3. 架构总览
|
||
4. Monorepo 结构与包职责
|
||
5. 前端架构
|
||
6. 后端架构
|
||
7. 数据层（PostgreSQL 18 + Prisma 7）
|
||
8. Redis、队列与实时
|
||
9. 文件与对象存储
|
||
10. 平台适配与 Playwright
|
||
11. 图片产线
|
||
12. AI 网关
|
||
13. 认证、权限、凭据与安全
|
||
14. 工程规范与质量门禁
|
||
15. 开发环境与命令
|
||
16. 构建与部署
|
||
17. 版本治理
|
||
18. 与评估文档的差异
|
||
19. M0 必须验证的风险
|
||
20. 明确不采用的技术与理由
|
||
21. 附录 A：`.npmrc` 与根配置
|
||
22. 附录 B：依赖清单
|
||
23. 附录 C：待确认项
|
||
|
||
---
|
||
|
||
## 0 定稿结论（一页纸）
|
||
|
||
| 决策 | 定稿 | 关键理由 |
|
||
|---|---|---|
|
||
| 运行时 | **Node.js 24.15.0（精确版本）** | 与开发机一致；Prisma 7 引擎要求 `^24.11`；Vite 8 要求 `>=22.12` |
|
||
| 包管理 | **pnpm 11.4.0（唯一）** | 与开发机一致；workspace 严格依赖；**不使用 npm** |
|
||
| 语言 | TypeScript **5.9.3**（strict） | typescript-eslint 8.72 要求 `<6.1`，暂不上 TS 7 |
|
||
| 前端 | React **19.3.1** + **Semi Design 2.104.0** + **Tailwind CSS 4.3.3** + Vite **8.3.5** | Semi 支持 React 19（dewu 已验证）；Tailwind 4 由 scgf 验证；Vite 8 满足 Tailwind/Semi 插件 |
|
||
| 后端 | **Express 5.3.0** + **Prisma 7.10.1** + **PostgreSQL 18** + **Redis 7** + **BullMQ 6.5.0** | Express 5 可迁移 scgf 中间件；Prisma 7 是当前稳定线（8 仍为 RC）；PG/Redis 已在本机运行 |
|
||
| 数据访问 | **Prisma 7.10.1 + `@prisma/adapter-pg`**（ESM） | 类型安全、迁移一体化；19 表模型需重写（+8~12 人日，见 §18） |
|
||
| 队列/实时 | BullMQ 5 类队列 + **SSE**（不用 WebSocket） | 任务进度是单向流；SSE 对 nginx/公网更友好 |
|
||
| 图像 | sharp **0.32.6（锁定）** + ag-psd **30.1.0** + @napi-rs/canvas **0.1.97** + fontkit **2.0.4** + ONNX 抠图 | 与 scgf 图像引擎行为一致，降低存量模板回归风险 |
|
||
| 平台自动化 | **Playwright 1.64.1**（独立 platform-worker） | 送审必须页面自动化；独立进程隔离；账号级串行锁 |
|
||
| 部署 | **单机 Docker Compose**（api + 4 worker + web/nginx） | 首期够用；代码保持无本地状态，后续可平滑扩副本 |
|
||
| 对象存储 | **开发本地磁盘 / 生产 OSS（S3 适配层）** | 开发机不新增容器；生产支持多副本与签名 URL |
|
||
| 数据库/缓存部署 | **复用开发机已有 Docker（PG 18 / Redis 7），平台不负责安装** | 用户明确要求；`.env` 直连 localhost |
|
||
|
||
> **与评估文档的差异**（详见 §18）：ORM 由评估时的 Sequelize 改为 **Prisma**，工作量 **+8~12 人日**（全量 383~569 → **391~581 人日**）；UI 由评估的 Tailwind 3 改为 **Tailwind 4**（+1~3 人日验证，在不确定性内）；其余方案不变。
|
||
|
||
---
|
||
|
||
## 1 决策依据与约束
|
||
|
||
### 1.1 硬约束（用户已确认）
|
||
|
||
| 约束 | 值 | 来源 |
|
||
|---|---|---|
|
||
| Node.js | **24.15.0** | 与开发机一致 |
|
||
| 包管理 | **pnpm**，非必要不用 npm | 用户明确要求 |
|
||
| PostgreSQL | **18**（开发机 Docker `postgres:18-alpine`，实际 18.4，5432） | 用户明确要求 |
|
||
| Redis | **7**（开发机 Docker `redis:7-alpine`，实际 7.4.9，6379） | 用户明确要求 |
|
||
| 部署 | 内部平台，但**公网可访问 + 登录鉴权** | 用户确认 |
|
||
| 对象存储 | 开发本地磁盘，生产 OSS | 用户确认 |
|
||
| 数据库/缓存 | 开发前直接开启已有容器，平台不做安装/编排 | 用户明确要求 |
|
||
| 形态 | 统一 WEB 平台，桌面端停止演进 | 用户确认 |
|
||
| 工程 | 新建统一工程 + 迁移两个参考项目资产 | 用户确认 |
|
||
| UI | Semi Design 最新版（支持 React 19）+ Tailwind CSS 4 | 用户确认 |
|
||
| ORM | Prisma | 用户确认 |
|
||
|
||
### 1.2 参考项目继承关系
|
||
|
||
| 资产 | 来源 | 在本工程中的处理 |
|
||
|---|---|---|
|
||
| 认证/口令安全/RBAC/客户范围/系统配置/任务事件/通知/导出 | scgf `backend/src` | 迁移业务逻辑；**数据访问层改为 Prisma**，模型重写 |
|
||
| PSD 解析/合成/抠图/字体/命名引擎 | scgf `utils/*` | 代码级迁移；渲染行为锁定（sharp/ag-psd/canvas 版本不变） |
|
||
| 星光签名/字段映射/送审命名/混剪规则/DPLink/审核 CSV | dewu `scripts/lib/*`、`electron/platform/*` | 抽为 `packages/domain` / `packages/platform-dewu`；纯逻辑几乎原样迁移 |
|
||
| 送审批次策略（串行/幂等/回查/审计） | dewu `electron/submit/*` | 迁移逻辑，存储改 DB + Redis |
|
||
| 只读接口层、商品详情 SSR 直取 | dewu `electron/platform/*`、`shop/detail.ts` | 服务端化，去掉 Electron |
|
||
| Electron 外壳/更新/签名/窗口/本地文件 | dewu `electron/*` | 废弃 |
|
||
| 页面信息架构（选品/物料/审核/送审/投放） | dewu `src/pages/*` | 交互参考；组件按 Semi 2.104 重写 |
|
||
| 页面信息架构（模板/生产/任务/配置） | scgf `frontend/src/pages/*` | 交互参考；按新 IA 重写 |
|
||
|
||
### 1.3 本机实测结论（定稿依据）
|
||
|
||
| 项 | 实测 | 结论 |
|
||
|---|---|---|
|
||
| Node | `v24.15.0` | 与要求一致；Prisma 7 要求 `^24.11`，满足 |
|
||
| pnpm | `11.4.0` | 锁定；`packageManager` 写 11.4.0 |
|
||
| PG | `PostgreSQL 18.4`（alpine，5432） | 直连；使用 PG18 原生 `uuidv7()` |
|
||
| Redis | `redis_version:7.4.9`（6379） | BullMQ 6 支持 Redis 7 |
|
||
| 图像原生依赖 | sharp 0.32.6、ag-psd 30.1.0、@napi-rs/canvas 0.1.97、fontkit 2.0.4、@imgly/background-removal-node 1.4.5 均可在 Node 24.15 arm64 加载（libvips 8.14.5） | 锁定该组合作为图像基线 |
|
||
| pnpm registry 最新版本 | Semi 2.104.0、Tailwind 4.3.3、Vite 8.3.5、Prisma 7.10.1、Express 5.3.0、BullMQ 6.5.0、Playwright 1.64.1 | 见 §2 版本总表 |
|
||
|
||
---
|
||
|
||
## 2 技术栈总表（版本锁定）
|
||
|
||
> 标记 **🔒** 的为精确锁定（升级需回归/评审）；其余使用 caret 范围 + 提交 lockfile。
|
||
> 版本以 2026-10-30 查询/实测为准；`pnpm-lock.yaml` 是唯一事实来源。
|
||
|
||
### 2.1 运行时与工具链
|
||
|
||
| 类别 | 技术 | 版本 | 说明 |
|
||
|---|---|---|---|
|
||
| 运行时 | Node.js | **24.15.0 🔒** | `.nvmrc`、`engines`、Docker 镜像三处一致 |
|
||
| 包管理 | pnpm | **11.4.0 🔒** | `packageManager`；corepack；禁止 npm |
|
||
| 语言 | TypeScript | **5.9.3 🔒** | strict；typescript-eslint 8.72 要求 `<6.1` |
|
||
| 开发执行 | tsx | 4.23.15 | 后端/脚本热执行 |
|
||
| 构建 | Vite | **8.3.5 🔒** | 前端；Node `>=22.12` |
|
||
| Lint | ESLint | **10.13.0 🔒** | flat config |
|
||
| Lint | typescript-eslint | **8.72.1 🔒** | 支持 ESLint 8/9/10、TS `<6.1` |
|
||
| 格式 | Prettier | 3.9.10 | 与 ESLint 分离 |
|
||
| 单测 | Vitest | **5.0.5 🔒** | 支持 Vite 8 |
|
||
| 覆盖率 | @vitest/coverage-v8 | 5.0.5 | — |
|
||
| E2E | Playwright | **1.64.1 🔒** | 同时用于平台自动化；浏览器版本随包锁定 |
|
||
|
||
### 2.2 前端
|
||
|
||
| 类别 | 技术 | 版本 | 说明 |
|
||
|---|---|---|---|
|
||
| 框架 | React / react-dom | **19.3.1 🔒** | Semi 2.104 支持 React 19 |
|
||
| 路由 | react-router-dom | 7.18.5 | Data Router；路由级 lazy |
|
||
| 组件库 | @douyinfe/semi-ui | **2.104.0 🔒** | 最新稳定；zh_CN、暗色、Table/Form/Upload/Tree |
|
||
| 组件库构建 | @douyinfe/semi-vite-plugin | **2.104.0 🔒** | 主题/CSS Layer；peer vite `>=3` |
|
||
| 图标 | @remixicon/react | 4.9.0 | 与 Semi 搭配 |
|
||
| CSS | Tailwind CSS | **4.3.3 🔒** | `@tailwindcss/vite` 4.3.3；`@theme` token |
|
||
| 构建插件 | @vitejs/plugin-react | **6.1.2 🔒** | peer Vite `^8`；React 19 |
|
||
| 状态 | zustand | 5.0.16 | 会话/UI 状态 |
|
||
| 服务端状态 | @tanstack/react-query | 5.105.0 | 列表/轮询/缓存 |
|
||
| HTTP | axios | 1.21.0 | 拦截器、刷新令牌、上传进度 |
|
||
| 表单 | react-hook-form | 7.91.0 | 复杂表单 |
|
||
| 校验 | @hookform/resolvers + zod | 6.0.2 / 4.6.7 | 与后端共享 schema |
|
||
| 图表 | recharts | 3.10.1 | Dashboard |
|
||
| 日期 | dayjs | 1.11.23 | zh-cn |
|
||
| Markdown | marked | 18.1.2 | 发版说明/富文本白名单渲染 |
|
||
| 测试 | @testing-library/react | 16.3.3 | React 19；配合 jsdom 30.1.3 |
|
||
|
||
### 2.3 后端
|
||
|
||
| 类别 | 技术 | 版本 | 说明 |
|
||
|---|---|---|---|
|
||
| Web 框架 | Express | **5.3.0 🔒** | 迁移 scgf 中间件；不选 Nest/Fastify |
|
||
| ORM | Prisma | **7.10.1 🔒** | 稳定线；8 仍为 RC，不采用 |
|
||
| ORM 客户端 | @prisma/client | **7.10.1 🔒** | ESM；`prisma-client` 生成器 |
|
||
| PG 驱动适配 | @prisma/adapter-pg | **7.10.1 🔒** | 连接 PG18 |
|
||
| PG 驱动 | pg | 8.23.1 | 适配器/运维脚本/健康检查 |
|
||
| 数据库 | PostgreSQL | **18（18.4）🔒** | 已有 Docker；PG18 `uuidv7()` |
|
||
| 缓存/队列 | Redis | **7（7.4.9）🔒** | 已有 Docker |
|
||
| Redis 客户端 | ioredis | **6.0.0 🔒** | BullMQ 6 推荐 |
|
||
| 队列 | BullMQ | **6.5.0 🔒** | 5 类队列；Redis 7 兼容 |
|
||
| 鉴权 | jsonwebtoken | 9.0.3 | access/refresh + pwdv |
|
||
| 密码 | bcrypt | 6.0.0 | 复用 scgf 策略 |
|
||
| 上传 | multer | 2.5.0 | 内存/临时盘；大文件直传 OSS |
|
||
| 校验 | zod | 4.6.7 | DTO/环境变量/表单共享 |
|
||
| 日志 | pino + pino-http | 10.4.0 / 11.0.0 | 结构化 JSON |
|
||
| 安全头 | helmet | 8.3.0 | 公网暴露必配 |
|
||
| CORS | cors | 2.8.6 | 白名单 |
|
||
| 压缩 | compression | 1.8.2 | 静态/JSON |
|
||
| 限流 | express-rate-limit + rate-limit-redis | 8.7.2 / 6.0.2 | Redis 共享限流 |
|
||
| 打包 | archiver | 8.0.0 | ZIP level 9 |
|
||
| 表格 | exceljs | 4.4.0 | CSV/XLSX 导入导出 |
|
||
| ID | uuid | 14.0.3 | 仅应用侧特殊场景；主键用 PG `uuidv7()` |
|
||
| 环境变量 | dotenv | 18.0.9 | dev 加载；prod 由编排注入 |
|
||
| 指标 | prom-client | 15.1.3 | `/metrics` |
|
||
| 对象存储 | @aws-sdk/client-s3 + presigner | 3.1160.0 | S3/MinIO |
|
||
| 阿里云 OSS | ali-oss | 6.23.0 | 生产 OSS 驱动 |
|
||
| MFA（管理员） | otplib | 13.5.0 | TOTP；公网暴露必配 |
|
||
|
||
### 2.4 图像 / PSD / 平台 / AI
|
||
|
||
| 类别 | 技术 | 版本 | 说明 |
|
||
|---|---|---|---|
|
||
| 图像处理 | sharp | **0.32.6 🔒** | 与 scgf 引擎行为一致；不可随意升级 |
|
||
| PSD 解析 | ag-psd | **30.1.0 🔒** | 图层读取 |
|
||
| Canvas | @napi-rs/canvas | **0.1.97 🔒** | 合成画布 |
|
||
| 字体 | fontkit | **2.0.4 🔒** | 字体名/排版 |
|
||
| 抠图 | @imgly/background-removal-node | **1.4.5 🔒** | ONNX medium；独立 Worker |
|
||
| 浏览器自动化 | Playwright | **1.64.1 🔒** | platform-worker；Chromium 版本随包 |
|
||
| AI Provider | 火山方舟 Seedream（图片）/ 视频模型待选 | 通过 REST 适配 | 不绑定 SDK；密钥只走环境变量 |
|
||
| AI 校验 | VLM（文字逐字/合规） | 通过 REST 适配 | 可插拔 provider |
|
||
|
||
### 2.5 为什么是这些版本（关键兼容性证据）
|
||
|
||
| 组合 | 证据 |
|
||
|---|---|
|
||
| Node 24.15 + Prisma 7.10.1 | Prisma engines：`^22.18 \|\| ^24.11 \|\| >=26`；`@prisma/client`：`^20.19 \|\| ^22.12 \|\| >=24.0` |
|
||
| Vite 8.3.5 + Node 24.15 | Vite engines：`^20.19.0 \|\| >=22.12.0` |
|
||
| Vite 8 + Tailwind 4 | `@tailwindcss/vite` peer：`^5.2 \|\| ^6 \|\| ^7 \|\| ^8` |
|
||
| Vite 8 + Semi 插件 | `semi-vite-plugin` peer：`vite >=3` |
|
||
| Vite 8 + plugin-react 6.1.2 | peer `vite ^8`；其 oxc/babel peer 均为 optional |
|
||
| React 19.3 + Semi 2.104 | Semi peer `react >=16`；dewu 已在 React 19.3 + Semi 2.103 生产验证 |
|
||
| TS 5.9.3 + typescript-eslint 8.72 | typescript-eslint peer `typescript >=4.8.4 <6.1.0`（故不选 TS 7.0.2） |
|
||
| ESLint 10 + typescript-eslint 8.72 | peer 支持 `^10.0.0` |
|
||
| BullMQ 6.5 + Redis 7.4 | BullMQ peer `ioredis >=5`、Node `>=14.18`；Redis 7 兼容 |
|
||
| 图像栈 + Node 24 arm64 | 本机实测 5 个原生包全部加载成功（libvips 8.14.5） |
|
||
|
||
---
|
||
|
||
## 3 架构总览
|
||
|
||
### 3.1 运行拓扑（开发环境）
|
||
|
||
> 开发机不新增 PG/Redis 容器：平台进程直接连已有 Docker；文件落本地目录。
|
||
|
||
```
|
||
┌───────────────────────────── macOS 开发机 ─────────────────────────────┐
|
||
│ │
|
||
│ 浏览器 ──http://localhost:5173──▶ Vite dev server（apps/web） │
|
||
│ │ /api 代理 │
|
||
│ ▼ │
|
||
│ apps/api（Express 5，:8300） │
|
||
│ │ │ │
|
||
│ │ ├──▶ PostgreSQL 18.4 :5432 │
|
||
│ │ │ (Docker 已有) │
|
||
│ │ ├──▶ Redis 7.4.9 :6379 │
|
||
│ │ │ (Docker 已有) │
|
||
│ │ └──▶ 本地磁盘 ./var/uploads │
|
||
│ │ │
|
||
│ 独立进程（pnpm dev:workers）： ▼ │
|
||
│ worker-image（PSD/合成/抠图） worker-platform（Playwright 有头/无头） │
|
||
│ worker-ai（生图/视频） worker-export（ZIP/CSV/打包） │
|
||
│ │ │
|
||
│ └──▶ BullMQ 队列（Redis） │
|
||
└────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 运行拓扑（生产）
|
||
|
||
```
|
||
公网（HTTPS）
|
||
│
|
||
┌────────▼────────┐
|
||
│ WAF / 云防护 │ （可选但建议）
|
||
└────────┬────────┘
|
||
┌────────▼────────┐
|
||
│ nginx（web 镜像）│ SPA + /api 反代 + SSE + /files
|
||
└────────┬────────┘
|
||
│
|
||
┌────────────────────┼────────────────────┬────────────────────┐
|
||
▼ ▼ ▼ ▼
|
||
api ×1~N worker-image ×1~N worker-platform ×1 worker-export/ai
|
||
│ │ │ │
|
||
└──────────┬─────────┴──────────┬─────────┴──────────┬─────────┘
|
||
▼ ▼ ▼
|
||
PostgreSQL 18 Redis 7 对象存储（OSS/S3）
|
||
（托管/独立容器） （队列/锁/限流） （物料/成片/导出包）
|
||
```
|
||
|
||
**关键设计**：
|
||
- API 无状态（会话在 JWT/Redis；文件在对象存储）→ 可水平扩副本。
|
||
- Worker 按负载类型拆进程：图像/抠图吃 CPU+内存，Playwright 吃内存+浏览器，AI 吃网络等待，导出吃 IO。
|
||
- 平台账号写操作在 `worker-platform` 内**按账号串行**，API 不直接开浏览器。
|
||
|
||
### 3.3 请求与任务链路
|
||
|
||
```
|
||
同步请求：浏览器 → nginx → api → Prisma(PG) → 返回
|
||
异步任务：api 建任务行（PG）→ 入 BullMQ（jobId = taskId）→ worker 执行
|
||
→ 更新任务行 + 写 task_event → Redis Pub/Sub → api SSE → 浏览器
|
||
文件：上传 → api 签发上传凭证（或本地直存）→ 对象存储/本地盘 → 记录 storage_key
|
||
下载 → api 校验权限 → 302 签名 URL / 流式代理
|
||
```
|
||
|
||
---
|
||
|
||
## 4 Monorepo 结构与包职责
|
||
|
||
### 4.1 目录
|
||
|
||
```
|
||
lingxi/
|
||
├── package.json # 根：scripts、engines、packageManager
|
||
├── pnpm-workspace.yaml
|
||
├── pnpm-lock.yaml # 唯一事实来源
|
||
├── .nvmrc # 24.15.0
|
||
├── .npmrc # engine-strict=true 等
|
||
├── tsconfig.base.json
|
||
├── prisma/
|
||
│ ├── schema.prisma # 唯一 schema
|
||
│ ├── migrations/ # prisma migrate 生成
|
||
│ └── seed.ts
|
||
├── apps/
|
||
│ ├── web/ # React 19 + Semi + Tailwind 4（Vite 8）
|
||
│ ├── api/ # Express 5（BFF + 业务 API）
|
||
│ ├── worker-image/ # sharp/ag-psd/canvas/抠图
|
||
│ ├── worker-platform/ # Playwright：登录/送审/审核/投放
|
||
│ ├── worker-ai/ # 生图/视频
|
||
│ └── worker-export/ # ZIP/CSV/XLSX
|
||
├── packages/
|
||
│ ├── shared/ # zod schema、DTO、错误码、枚举、类型
|
||
│ ├── domain/ # 命名引擎、送审规则、DPLink、审核映射（纯逻辑）
|
||
│ ├── platform-dewu/ # 星光签名/只读接口/页面自动化
|
||
│ ├── platform-vipshop/ # 唯品会适配（M3 起）
|
||
│ ├── db/ # Prisma client 单例、事务工具、Repository
|
||
│ ├── storage/ # StorageAdapter（local / s3 / oss）
|
||
│ ├── ai/ # Provider 接口 + Ark 实现 + 成本核算
|
||
│ └── ui/ # 设计 token + Semi 封装 + 通用组件
|
||
├── infra/
|
||
│ ├── docker/ # 各镜像 Dockerfile
|
||
│ ├── nginx/ # SPA + API + SSE + /files
|
||
│ ├── compose/ # dev/prod compose
|
||
│ └── scripts/ # db-create、备份、健康检查
|
||
├── test/
|
||
│ ├── integration/ # PG/Redis 集成测试
|
||
│ ├── golden/ # PSD 黄金样本 + 像素 diff
|
||
│ └── e2e/ # Playwright
|
||
└── docs/
|
||
```
|
||
|
||
### 4.1.1 模块规范
|
||
|
||
- 全仓库 **ESM**：各包 `package.json` 设 `"type": "module"`，`tsconfig` 用 `module: NodeNext` + `verbatimModuleSyntax`。
|
||
- Prisma 7 使用 `prisma-client` 生成器产出 ESM client，统一从 `@lingxi/db` 导入。
|
||
- 后端构建用 `tsc`（ESM 输出），开发用 `tsx`；不使用 CommonJS `require`。
|
||
- 禁止跨包相对路径引用；统一 `@lingxi/*` workspace 协议。
|
||
|
||
### 4.2 包依赖规则
|
||
|
||
| 规则 | 说明 |
|
||
|---|---|
|
||
| `apps/*` 不得被其他包依赖 | 应用是组合根 |
|
||
| `packages/domain` 只依赖 `shared` | 纯逻辑、可单测、不碰 DB/HTTP |
|
||
| `packages/platform-*` 依赖 `domain` + `shared` | 平台协议/页面自动化；不反向依赖 API |
|
||
| `packages/db` 只暴露 Prisma client 与 Repository | 禁止业务直接 import Prisma client 到处用 |
|
||
| `packages/ui` 只依赖 React/Semi/Tailwind | 不含业务请求 |
|
||
| 跨包引用走 `@lingxi/*` workspace 协议 | `pnpm` 严格链接，禁止相对路径穿透 |
|
||
|
||
### 4.3 根 scripts（只用 pnpm）
|
||
|
||
```json
|
||
{
|
||
"packageManager": "pnpm@11.4.0",
|
||
"engines": { "node": "24.15.0", "pnpm": "11.4.0" },
|
||
"scripts": {
|
||
"dev": "pnpm --parallel -r --filter @lingxi/web --filter @lingxi/api run dev",
|
||
"dev:workers": "pnpm --parallel -r --filter './apps/worker-*' run dev",
|
||
"build": "pnpm -r build",
|
||
"lint": "eslint .",
|
||
"format": "prettier --write .",
|
||
"typecheck": "pnpm -r typecheck",
|
||
"test": "vitest run",
|
||
"test:integration": "vitest run -c vitest.integration.config.ts",
|
||
"test:e2e": "playwright test",
|
||
"db:create": "tsx infra/scripts/db-create.ts",
|
||
"db:migrate": "prisma migrate dev",
|
||
"db:deploy": "prisma migrate deploy",
|
||
"db:seed": "prisma db seed",
|
||
"db:studio": "prisma studio",
|
||
"playwright:install": "playwright install chromium"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5 前端架构（React 19 + Semi 2.104 + Tailwind 4）
|
||
|
||
### 5.1 应用结构
|
||
|
||
```
|
||
apps/web/src/
|
||
├── app/ # 入口、路由、Provider、错误边界
|
||
├── layouts/ # 侧边栏/顶栏/权限布局
|
||
├── features/
|
||
│ ├── platform/ # 平台切换
|
||
│ ├── selection/ # 选品/圈选/历史
|
||
│ ├── materials/ # 原始物料
|
||
│ ├── image/ # 模板/制作/批量/预览
|
||
│ ├── video/ # 脚本/画面/成片
|
||
│ ├── review/ # 提审/审核
|
||
│ ├── delivery/ # 投放配置/DPLink
|
||
│ ├── assets/ # 模板/Logo/展示/促销/脚本资产
|
||
│ └── system/ # 用户/角色/客户/配置/任务日志
|
||
├── shared/ # api client、hooks、utils、权限、i18n
|
||
└── styles/ # tailwind.css、semi-theme.css、tokens.css
|
||
```
|
||
|
||
- 路由：`react-router-dom` 7 Data Router；按 `features` 懒加载；路由守卫统一在 `app/routes.tsx`。
|
||
- 权限：后端 `/auth/me` 返回 `permissions[]`；菜单/按钮用 `<Can permission="...">`；**前端不作为安全边界**，后端每个接口独立校验。
|
||
- 状态：服务端状态全部走 TanStack Query；仅会话/主题/布局用 zustand。禁止把列表数据塞 zustand。
|
||
- 请求：单一 `shared/api/client.ts`（axios）；自动附加 access token；401 触发一次 refresh；失败统一 toast + 错误码映射。
|
||
- 表单：react-hook-form + zod（schema 来自 `@lingxi/shared`），Semi Form 作为展示层。
|
||
|
||
### 5.2 Semi 2.104 + Tailwind 4 集成（必须按此顺序，否则静默失效）
|
||
|
||
```css
|
||
/* apps/web/src/styles/index.css —— 顺序 = 层叠优先级（M0 Spike 最终确认） */
|
||
@layer theme, base, semi, components, utilities;
|
||
|
||
@import "tailwindcss";
|
||
@import "@douyinfe/semi-ui/dist/css/semi.min.css" layer(semi);
|
||
@import "./semi-theme.css" layer(semi); /* Semi CSS 变量覆盖 */
|
||
@import "./tokens.css"; /* 品牌 token（@theme） */
|
||
```
|
||
|
||
**硬性约定**：
|
||
1. `@import` 顺序即层叠顺序：Tailwind base → Semi → 主题 token → 页面样式；页面级样式不得写未分层的 `* { margin:0 }`。
|
||
2. 品牌色/圆角/字号只允许在 `tokens.css` 的 `@theme` 与 `semi-theme.css` 的 `--semi-color-*` 定义，页面禁止硬编码色值（CI 用脚本校验）。
|
||
3. 不使用 `.semi-*` 内部类做覆盖；只通过 Semi 语义 token 与 `ConfigProvider`。
|
||
4. 组件统一从 `@lingxi/ui` 导出（薄封装 Semi），页面不直接 import Semi 的内部组件，便于后续换肤/升级。
|
||
5. **M0 必须先做构建 Spike**：Semi 2.104 + Tailwind 4.3 + Vite 8 同时引入，验证 modal/drawer/table 样式与 `@layer` 顺序；失败则回退方案见 §19 R1。
|
||
|
||
### 5.3 页面与路由（首期）
|
||
|
||
| 路由 | 页面 | 首期 |
|
||
|---|---|---|
|
||
| `/` | 工作台/Dashboard | 是 |
|
||
| `/selection` | 选品（检索/圈选/历史） | 是 |
|
||
| `/materials` | 原始物料 | 是 |
|
||
| `/image/templates` | 模板资产 | 是 |
|
||
| `/image/produce` | 图片制作（三规格/四层合成/批量） | 是 |
|
||
| `/review` | 提审与审核 | 是（MVP-2） |
|
||
| `/delivery` | 投放配置/DPLink | 是（MVP-2） |
|
||
| `/assets` | 资产中心 | M4 |
|
||
| `/system/*` | 用户/角色/客户/配置/任务日志 | 是 |
|
||
| `/video/*` | 视频产线 | M5 |
|
||
|
||
### 5.4 构建与性能
|
||
|
||
- Vite 8：`build.target = es2022`；路由级 code-split；Semi 按需（插件已处理）。
|
||
- 图片列表用缩略图 URL（`?w=320`）；大图预览走原图/签名 URL。
|
||
- 表格默认分页 20/50；超过 200 行启用虚拟滚动（Semi Table 支持）。
|
||
- 首屏预算：JS ≤ 350KB gzip（不含图片）；超过则拆包。
|
||
|
||
---
|
||
|
||
## 6 后端架构（Express 5）
|
||
|
||
### 6.1 分层
|
||
|
||
```
|
||
apps/api/src/
|
||
├── server.ts # 启动、优雅退出
|
||
├── app.ts # Express 装配（middleware 顺序）
|
||
├── routes/ # 路由声明（薄）
|
||
├── controllers/ # 参数校验 + 调 service
|
||
├── services/ # 业务编排（事务边界）
|
||
├── repositories/ # Prisma 查询封装（可测试）
|
||
├── middlewares/ # auth、scope、rateLimit、error、requestId
|
||
├── events/ # SSE、任务事件发布
|
||
└── jobs/ # 入队（只投递，不执行）
|
||
```
|
||
|
||
- **Controller 不写 SQL/Prisma**；Service 不直接读 `req`。
|
||
- 事务：Service 层用 `prisma.$transaction`；跨任务/文件操作先落库再入队。
|
||
- 错误：统一 `AppError(code, message, httpStatus, details)`；错误码在 `packages/shared/errors.ts`；响应不泄露堆栈。
|
||
- 请求 ID：`x-request-id` 透传 pino；审计与日志可关联。
|
||
|
||
### 6.2 API 规范
|
||
|
||
| 项 | 约定 |
|
||
|---|---|
|
||
| 前缀 | `/api/v1` |
|
||
| 成功 | `{ "data": ..., "requestId": "..." }` |
|
||
| 失败 | `{ "error": { "code": "AUTH_401", "message": "...", "details": ... }, "requestId": "..." }` |
|
||
| 分页 | `?page=1&pageSize=20`；返回 `{ items, total, page, pageSize }`；大列表用 cursor |
|
||
| 幂等 | 写操作支持 `Idempotency-Key`；任务创建以 `(batchId, templateId, productId)` 唯一约束兜底 |
|
||
| 时间 | ISO 8601 UTC；DB `timestamptz` |
|
||
| 文件 | 上传走 `POST /files/presign`（生产）或 `POST /files/upload`（开发本地） |
|
||
| 实时 | `GET /api/v1/events?topics=batch:{id}`（SSE） |
|
||
| 文档 | zod → OpenAPI（dev 环境 `/api/docs`）；不维护手写文档 |
|
||
|
||
### 6.3 中间件顺序（固定）
|
||
|
||
```
|
||
requestId → pino-http → helmet → cors 白名单 → compression（跳过 SSE）
|
||
→ body parser（json 2mb / urlencoded）→ cookie parser
|
||
→ 全局限流（Redis）→ 路由
|
||
→ 404 → error handler（统一信封）
|
||
```
|
||
|
||
- `helmet` 在公网必须开启；`cors` 只允许 `WEB_ORIGIN`。
|
||
- SSE 路由放在 `compression` 之后但显式跳过压缩，并设置 `Cache-Control: no-cache`、`X-Accel-Buffering: no`。
|
||
- 上传路由使用 multer 单独限制大小与 MIME，不适用全局 body 限制。
|
||
|
||
### 6.4 健康检查与可观测
|
||
|
||
| 端点 | 用途 |
|
||
|---|---|
|
||
| `GET /health/live` | 进程存活（不查依赖） |
|
||
| `GET /health/ready` | DB/Redis/对象存储探活；失败 503 |
|
||
| `GET /metrics` | Prometheus（内部网段/鉴权） |
|
||
|
||
- 日志：pino JSON；字段 `requestId/userId/platformId/taskId`；**禁止打印 token/密码/签名盐**。
|
||
- 指标：HTTP P95、队列积压、任务成功率/时长、图像处理耗时、AI 调用成本。
|
||
|
||
---
|
||
|
||
## 7 数据层（PostgreSQL 18 + Prisma 7.10.1）
|
||
|
||
### 7.1 Prisma 约定
|
||
|
||
- 生成器：Prisma 7 的 `prisma-client`（ESM），输出到 `packages/db/src/generated/prisma`；应用统一从 `@lingxi/db` 导入。
|
||
- 连接：`@prisma/adapter-pg`（driver adapter）+ `pg`；连接池 `max=10`（API）/`max=3`（Worker），按实例数核算 PG `max_connections`。
|
||
- 迁移：本地 `prisma migrate dev`；CI/生产 `prisma migrate deploy`；**禁止 `db push` 到生产**。
|
||
- 命名：`@@map("snake_case")`、`@map("snake_case")`；Prisma 字段 camelCase，DB 列 snake_case。
|
||
- 主键：`String @id @default(dbgenerated("uuidv7()")) @db.Uuid`（PG18 原生 `uuidv7()`，时间有序、索引友好）。
|
||
- 时间：`DateTime @db.Timestamptz(6)`；统一 UTC。
|
||
- JSON：`Json`（映射 JSONB）；仅用于配置/快照/扩展字段，不用于高频过滤。
|
||
- 软删除：`deletedAt DateTime?`；查询统一走 Repository 的 `notDeleted`。
|
||
- 枚举：稳定集合用 Prisma enum；运营可维护的字典用表（如失败原因、类目）。
|
||
- 索引：`platform_id/client_id/status/created_at` 组合；任务表 `(status, created_at)`；事件表 `(task_id, created_at)`。
|
||
|
||
### 7.2 初始 schema 范围（与评估 §5.6 对齐）
|
||
|
||
| 域 | 表（Prisma model） |
|
||
|---|---|
|
||
| 组织 | `Platform`、`Project`、`Client`、`User`、`Role`、`UserClient` |
|
||
| 凭据 | `PlatformAccount`（能力：soft/hard/review；密文；归属） |
|
||
| 商品/选品 | `ProductSnapshot`、`SelectionBatch`、`SelectionItem` |
|
||
| 物料 | `RawAsset` |
|
||
| 模板/资产 | `Template`、`TemplateCategory`、`TemplateTag`、`TemplateTagRelation`、`TemplateSpec`、`Asset` |
|
||
| 生产 | `ProductionBatch`、`ProductionTask`、`Material`、`NamingRule` |
|
||
| 提审 | `ReviewTicket`、`ReviewItem`、`SubmitLedger` |
|
||
| 投放 | `DeliveryConfig`、`DeliveryLink` |
|
||
| 任务/通知 | `TaskEvent`、`FailureCatalog`、`Notification`、`NotificationTemplate` |
|
||
| 配置/审计 | `SystemConfig`、`SystemConfigAudit`、`UserAudit`、`OperationAudit` |
|
||
|
||
> 共约 33 张表；与评估文档的数据模型一致，仅访问层从 Sequelize 改为 Prisma。
|
||
|
||
### 7.3 迁移与种子
|
||
|
||
- 初始化：`pnpm db:create`（Node 脚本连 `postgres` 库，`CREATE DATABASE lingxi`，不存在才建）→ `pnpm db:migrate` → `pnpm db:seed`。
|
||
- 种子：管理员账号（口令随机、仅显示一次）、基础角色/权限、得物平台、默认规格（800×800 / 1280×720 / 1080×1920）、字典。根 `package.json` 需声明 `"prisma": { "seed": "tsx prisma/seed.ts" }`。
|
||
- 回滚：Prisma 迁移是前向的；破坏性变更采用 expand/contract（先加列/双写，再切读，最后删列），保留 down 说明在迁移目录 README。
|
||
- 备份：生产每日 `pg_dump` + WAL；迁移前强制快照。
|
||
|
||
### 7.4 数据隔离
|
||
|
||
- 单租户（内部平台）；数据范围：`platformId` + `clientId`。
|
||
- 所有列表查询必须带范围条件（Repository 强制参数）；`fail-closed`：无范围 = 查不到，而不是全量。
|
||
- 审计表不做外键级联，保留历史。
|
||
|
||
---
|
||
|
||
## 8 Redis、队列与实时
|
||
|
||
### 8.1 Redis 使用边界
|
||
|
||
| 用途 | Key 前缀 | 说明 |
|
||
|---|---|---|
|
||
| BullMQ | `lingxi:bull:*` | 5 类队列 |
|
||
| 缓存 | `lingxi:cache:*` | 平台枚举/标签树/配置；TTL |
|
||
| 限流 | `lingxi:rl:*` | 登录、API、AI 调用 |
|
||
| 锁 | `lingxi:lock:account:{id}` 等 | `SET NX PX` + Lua 释放 |
|
||
| Pub/Sub | `lingxi:events` | SSE 广播 |
|
||
| 会话（可选） | `lingxi:sess:*` | 刷新令牌黑名单/设备 |
|
||
|
||
- Redis 7 已有；**不执行 `FLUSHALL`**；统一前缀，避免与其他项目冲突。
|
||
- 禁用 `KEYS`；批量用 `SCAN`。
|
||
- 本地开发使用 db 0；测试用 db 15（`REDIS_URL=.../15`）。
|
||
|
||
### 8.2 队列拓扑
|
||
|
||
| 队列 | 生产者 | 消费者 | 并发建议 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `image-render` | api | worker-image | 2~4 | PSD/合成/抠图；吃内存 |
|
||
| `platform-task` | api | worker-platform | 每账号 1 | 登录/送审/审核/投放；串行 |
|
||
| `ai-image` | api | worker-ai | 2~4 | 外部 API；限流/配额 |
|
||
| `ai-video` | api | worker-ai | 1~2 | 长任务；M5 |
|
||
| `export` | api | worker-export | 2 | ZIP/CSV；IO 密集 |
|
||
|
||
约定：`jobId = DB task id`；`attempts=3`（平台写操作只 1 次 + 回查）；指数退避；`removeOnComplete` 保留 1000/1 天；失败进 DLQ（`*-failed`）。DB 是事实来源；每 60s reconciler 扫描 `processing` 超时任务重新入队或标记失败。
|
||
|
||
### 8.3 SSE（任务进度）
|
||
|
||
- 端点：`GET /api/v1/events?topics=batch:{id},platform:{code}`；`text/event-stream`。
|
||
- 鉴权：登录 cookie/JWT（EventSource 不能带 header → 用短时 ticket：`POST /events/ticket` 换 60s ticket）。
|
||
- 服务端：worker 更新任务 → `publish(lingxi:events, {topic, seq, payload})` → 每个 api 实例订阅并 fan-out 给本实例 SSE 连接。
|
||
- 事件：`{ type: 'batch.progress' | 'task.status' | 'notification', topic, seq, ts, data }`。
|
||
- 心跳 15s；断线重连用 `Last-Event-ID`（seq 游标，保留最近 5 分钟环形缓冲）。
|
||
- nginx：单独 location，`proxy_buffering off; proxy_read_timeout 3600s;`。
|
||
|
||
### 8.4 分布式锁与幂等
|
||
|
||
- 账号锁：`SET lock:account:{id} <token> NX PX 900000`；释放用 Lua 比对 token；超时自动释放并告警。
|
||
- 任务幂等：DB 唯一约束 + `jobId`；重复投递由 BullMQ 去重。
|
||
- 提交幂等：`SubmitLedger`（md5）先查后提；平台返回重复码时按已提交处理。
|
||
- 限流：登录 5 次/分钟/IP+用户名；普通 API 300 次/分钟/用户；AI 按日配额。
|
||
|
||
---
|
||
|
||
## 9 文件与对象存储
|
||
|
||
### 9.1 StorageAdapter
|
||
|
||
```ts
|
||
export interface StorageAdapter {
|
||
put(key: string, body: Buffer | Readable, opts: { contentType: string; cacheControl?: string }): Promise<{ key: string; size: number; md5: string }>;
|
||
get(key: string): Promise<Readable>;
|
||
delete(key: string): Promise<void>;
|
||
exists(key: string): Promise<boolean>;
|
||
signDownload(key: string, ttlSeconds: number): Promise<string>;
|
||
copy(srcKey: string, dstKey: string): Promise<void>;
|
||
}
|
||
```
|
||
|
||
| 驱动 | 使用场景 | 实现 |
|
||
|---|---|---|
|
||
| `local` | 开发/单机 | `./var/uploads`；`/files/:key` 鉴权后流式返回；禁止路径穿越 |
|
||
| `s3` | MinIO/兼容 S3 | `@aws-sdk/client-s3` + presigner |
|
||
| `oss` | 阿里云 OSS 生产 | `ali-oss`（STS/签名 URL） |
|
||
|
||
- 配置：`STORAGE_DRIVER=local|s3|oss`；启动时 zod 校验必填项。
|
||
- Key 规则：`{platformCode}/{clientId}/{domain}/{yyyy}/{mm}/{uuid}.{ext}`；禁止使用客户端文件名作为 key。
|
||
- 缩略图：图片上传后由 `worker-image` 生成 `_thumb.webp`（`?w=320/640`）；清理任务按引用计数/保留期。
|
||
- 大文件（视频 140–190MB）：生产走浏览器/客户端直传 OSS（STS 临时凭证），API 只登记元数据；Playwright 送审时 worker 从对象存储下载到本地临时目录再 `setInputFiles`。
|
||
- 生命周期：原始物料默认长期保留；导出包 7~30 天；临时文件 24 小时。
|
||
|
||
---
|
||
|
||
## 10 平台适配与 Playwright（worker-platform）
|
||
|
||
### 10.1 适配器接口
|
||
|
||
```ts
|
||
export interface PlatformAdapter {
|
||
code: 'dewu' | 'vipshop';
|
||
capabilities: { read: boolean; write: boolean; submit: boolean; dplink: boolean };
|
||
login(ctx: AccountContext): Promise<LoginResult>;
|
||
searchProducts(q: SearchQuery): Promise<ProductBrief[]>;
|
||
getProduct(spuId: string): Promise<ProductSnapshot>;
|
||
listRawAssets(spuId: string): Promise<RawAssetRef[]>;
|
||
listMaterials(q: MaterialQuery): Promise<MaterialPage>;
|
||
submitReview(input: SubmitInput): Promise<SubmitResult>;
|
||
queryReview(input: ReviewQuery): Promise<ReviewPage>;
|
||
buildDeliveryLink(input: DeliveryLinkInput): Promise<DeliveryLink>;
|
||
}
|
||
```
|
||
|
||
- 得物：读链路走签名 HTTP（`packages/platform-dewu/http.ts`）；写链路默认页面自动化（`page.ts`），直连写接口作为 POC 备选。
|
||
- 唯品会：M3 开始，先摸登录/接口/提审流程，再实现同一接口。
|
||
- **不另开浏览器 context**：同一账号复用持久化 context；token 由凭据服务单写（API 只读，禁止自行重登）。
|
||
|
||
### 10.2 Worker 运行约束
|
||
|
||
| 项 | 约定 |
|
||
|---|---|
|
||
| 浏览器 | Chromium 版本随 Playwright 1.64.1 锁定；`pnpm playwright:install` 安装 |
|
||
| 账号并发 | 同一 `platformAccountId` 同时只允许 1 个写任务（Redis 锁） |
|
||
| 只读并发 | 全局上限 4；按平台限速 |
|
||
| 失败证据 | 截图 + DOM 快照 + reasonCode 存对象存储，DB 记录 key |
|
||
| 选择器 | 全部走配置（`selectors.dewu.json`），禁止散落硬编码；关键元素缺失触发健康告警 |
|
||
| 上传 | 大文件先落本地临时目录，`setInputFiles` 后清理；超时 15 分钟 |
|
||
| 重试 | 网络/5xx 重试 1 次；提交超时**只回查不重试** |
|
||
|
||
---
|
||
|
||
## 11 图片产线（worker-image）
|
||
|
||
- 输入：模板（PSD）+ 商品图 + 展示方式资产 + Logo + 促销模板 + 字段；输出：三规格图片 + 命名 + 元数据。
|
||
- 流程：`readPsd` → 资产快照 → 图层合成（保持 PSD z 序，按 `assetType` 取资产）→ 抠图（仅白底）→ 压缩（JPG 二分质量 / PNG 调色板）→ 写对象存储 → `Material` 落库。
|
||
- 版本：sharp 0.32.6 / ag-psd 30.1.0 / canvas 0.1.97 / fontkit 2.0.4 **锁定**；升级必须过黄金样本。
|
||
- 回归：`test/golden/` 存 ≥5 个真实模板 + 期望图；像素 diff 阈值（默认 mean diff < 0.5%，单像素阈值 8/255）；CI 跑 `pnpm test:golden`。
|
||
- 字体：内置字体清单与授权登记；换字体必须跑回归；缺字形时显式失败（不许"豆腐块但任务成功"）。
|
||
- 并发：worker-image 独立进程，默认 2 并发；内存上限监控，OOM 重启由容器策略兜底。
|
||
|
||
---
|
||
|
||
## 12 AI 网关（worker-ai）
|
||
|
||
### 12.1 接口
|
||
|
||
```ts
|
||
export interface AiImageProvider {
|
||
generate(input: ImageGenInput): Promise<ImageGenResult>; // 返回 storageKey/成本/耗时
|
||
checkText(input: TextCheckInput): Promise<TextCheckResult>; // VLM 逐字校验
|
||
}
|
||
```
|
||
|
||
- Provider：`ark`（火山方舟 Seedream，默认）；可插拔其他厂商。
|
||
- 模型分层：成品默认 `pro`，草稿/批量初筛用 `flash`；模型名/单价/限额全部配置化。
|
||
- 队列：`ai-image` / `ai-video`；按账号级并发与 RPM 限流；429 退避。
|
||
- 成本：每次调用写 `AiUsage`（provider/model/tokens/单价/金额/任务）；日/月预算告警；超限降级或拒绝。
|
||
- 合规：文字逐字校验 + 人工复核闸门 + 品牌 Logo 程序贴回；生成内容留痕（prompt/输出/审核人）。
|
||
- 密钥：只读环境变量/KMS；**禁止进 DB/系统配置/日志**。
|
||
|
||
---
|
||
|
||
## 13 认证、权限、凭据与安全
|
||
|
||
### 13.1 认证
|
||
|
||
| 项 | 约定 |
|
||
|---|---|
|
||
| Access Token | JWT，15 分钟，前端仅内存保存（不写 localStorage） |
|
||
| Refresh Token | httpOnly + Secure + SameSite=Strict Cookie，7 天，旋转 + 复用检测 |
|
||
| 口令 | bcrypt 12；策略复用 scgf（8–20 位、字母+数字、弱口令库、不得含用户名） |
|
||
| 强制改密 | 首次登录/管理员重置；服务端 403 `PASSWORD_CHANGE_REQUIRED` |
|
||
| 失效 | JWT 携带 `pwdv`；改密/重置递增，旧令牌立即失效 |
|
||
| MFA | 管理员与高权限角色强制 TOTP；公网暴露的前置 |
|
||
| 限流 | 登录 5 次/分钟/IP+用户名；失败锁定 15 分钟 |
|
||
|
||
### 13.2 权限
|
||
|
||
- RBAC：`admin / designer / optimizer / operator`；权限 key（如 `template.write`、`review.submit`、`delivery.manage`）。
|
||
- 数据范围：`platformId` × `clientId`；Repository 强制注入；越权返回 404（不泄露存在性）。
|
||
- 平台账号：`PlatformAccount.capabilities`（soft/hard/review）；使用账号需授权；敏感操作二次确认 + 审计。
|
||
|
||
### 13.3 凭据加密
|
||
|
||
- 算法：AES-256-GCM；密钥 `PLATFORM_CRED_KEY`（32 字节 base64，环境变量/KMS 注入）；AAD 绑定 `accountId`。
|
||
- 存储：`PlatformAccount.credentialCipher`（密文）+ `keyVersion`；轮换时后台重加密。
|
||
- 禁止：写入日志、审计 old/new 明文、系统配置表、前端响应。
|
||
|
||
### 13.4 公网暴露面
|
||
|
||
| 控制 | 要求 |
|
||
|---|---|
|
||
| HTTPS | TLS 1.2+；HSTS |
|
||
| WAF | 云 WAF/高防（建议）；至少 nginx + 限流 |
|
||
| 安全头 | helmet：CSP、X-Frame-Options、nosniff、Referrer-Policy |
|
||
| CORS | 仅 `WEB_ORIGIN` |
|
||
| MFA | 管理员强制；运营可配置 |
|
||
| 依赖/镜像 | CI `pnpm audit --prod`；镜像扫描 |
|
||
| 渗透测试 | 上线前 1 次；每年 1 次 |
|
||
| 备份 | PG 每日 + WAL；对象存储版本化 |
|
||
| 审计 | 登录、权限变更、凭据使用、提审/投放、导出 |
|
||
|
||
---
|
||
|
||
## 14 工程规范与质量门禁
|
||
|
||
### 14.1 TypeScript / Lint
|
||
|
||
- `strict: true`、`noUncheckedIndexedAccess`、`exactOptionalPropertyTypes`（新代码）；禁止 `any`（`unknown` + 收窄）。
|
||
- ESLint 10 flat config：`@typescript-eslint`、`react-hooks`、`import` 排序；`pnpm lint` 零 warning。
|
||
- Prettier 3.9：单引号、无分号、printWidth 100；`pnpm format:check` 入 CI。
|
||
- commitlint + cz-git（沿用 scgf 规范）：`feat/fix/docs/refactor/test/chore`。
|
||
|
||
### 14.2 测试分层
|
||
|
||
| 层 | 工具 | 范围 | 门禁 |
|
||
|---|---|---|---|
|
||
| 单元 | Vitest 5 | domain/命名/校验/成本 | 覆盖率 ≥ 70%（domain ≥ 85%） |
|
||
| 集成 | Vitest + PG/Redis 测试库 | Repository/事务/队列/SSE | 每次 PR |
|
||
| 契约 | Vitest + 抓包 fixture | 星光只读接口/字段映射 | 每次 PR |
|
||
| 黄金图 | Vitest + pixelmatch | PSD 合成/压缩 | 每次改图像代码 |
|
||
| E2E | Playwright 1.64 | 登录→选品→出图→提审 | 每日/M1 后 |
|
||
|
||
- 测试库：`lingxi_test`（PG）+ Redis db 15；每个测试文件事务回滚或 truncate。
|
||
- 不 mock 数据库（集成层）；外部平台用 fixture/mock server。
|
||
|
||
### 14.3 CI（pnpm only）
|
||
|
||
```
|
||
pnpm install --frozen-lockfile
|
||
pnpm lint
|
||
pnpm typecheck
|
||
pnpm test
|
||
pnpm db:deploy（测试库）
|
||
pnpm test:integration
|
||
pnpm test:golden
|
||
pnpm build
|
||
pnpm test:e2e（可选，需浏览器）
|
||
```
|
||
|
||
- 服务：`postgres:18-alpine`、`redis:7-alpine`（GitHub Actions services 或 GitLab services）。
|
||
- 缓存：pnpm store；Node 24.15.0 由 `.nvmrc`/action 指定。
|
||
- **任何步骤禁止 `npm install`**；如遇工具要求 npm，用 `pnpm dlx` 替代 `npx`。
|
||
|
||
---
|
||
|
||
## 15 开发环境与命令（本机）
|
||
|
||
### 15.1 前置（已具备）
|
||
|
||
| 项 | 本机 | 说明 |
|
||
|---|---|---|
|
||
| Node | 24.15.0 | `.nvmrc` 固定 |
|
||
| pnpm | 11.4.0 | `corepack enable` 后由 `packageManager` 锁定 |
|
||
| PG | 18.4 @ 127.0.0.1:5432 | Docker 已有；**平台不启动/不安装** |
|
||
| Redis | 7.4.9 @ 127.0.0.1:6379 | Docker 已有；**平台不启动/不安装** |
|
||
|
||
### 15.2 首次启动
|
||
|
||
```bash
|
||
corepack enable
|
||
pnpm install
|
||
cp .env.example .env # 填 PG 密码/JWT 密钥/凭据密钥
|
||
pnpm db:create # 连接 postgres 库，创建 lingxi（不存在才建）
|
||
pnpm db:migrate # prisma migrate dev
|
||
pnpm db:seed # 管理员/角色/平台/规格
|
||
pnpm playwright:install # 安装 Chromium（平台 Worker 需要）
|
||
pnpm dev # web:5173 + api:8300
|
||
# 另开终端：
|
||
pnpm dev:workers # 4 类 Worker
|
||
```
|
||
|
||
### 15.3 `.env.example`
|
||
|
||
```dotenv
|
||
NODE_ENV=development
|
||
PORT=8300
|
||
WEB_ORIGIN=http://localhost:5173
|
||
|
||
DATABASE_URL=postgresql://postgres:CHANGE_ME@127.0.0.1:5432/lingxi?schema=public
|
||
REDIS_URL=redis://127.0.0.1:6379/0
|
||
REDIS_PREFIX=lingxi
|
||
|
||
JWT_ACCESS_SECRET=CHANGE_ME_32+_CHARS
|
||
JWT_REFRESH_SECRET=CHANGE_ME_32+_CHARS
|
||
PLATFORM_CRED_KEY=base64:CHANGE_ME_32_BYTES
|
||
|
||
STORAGE_DRIVER=local
|
||
STORAGE_LOCAL_ROOT=./var/uploads
|
||
# STORAGE_DRIVER=s3
|
||
# S3_ENDPOINT=http://127.0.0.1:9000
|
||
# S3_REGION=us-east-1
|
||
# S3_BUCKET=lingxi
|
||
# S3_ACCESS_KEY_ID=
|
||
# S3_SECRET_ACCESS_KEY=
|
||
# STORAGE_DRIVER=oss
|
||
# OSS_REGION=oss-cn-shanghai
|
||
# OSS_BUCKET=
|
||
# OSS_ACCESS_KEY_ID=
|
||
# OSS_ACCESS_KEY_SECRET=
|
||
|
||
PLAYWRIGHT_BROWSERS_PATH=./.cache/ms-playwright
|
||
AI_PROVIDER=ark
|
||
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
|
||
ARK_API_KEY=
|
||
LOG_LEVEL=info
|
||
```
|
||
|
||
### 15.4 端口与目录
|
||
|
||
| 服务 | 端口 | 说明 |
|
||
|---|---|---|
|
||
| web | 5173 | Vite dev；`/api` 代理到 8300 |
|
||
| api | 8300 | 避开常见 3000，降低冲突 |
|
||
| PG | 5432 | 已有容器 |
|
||
| Redis | 6379 | 已有容器 |
|
||
| 本地文件 | `./var/uploads` | 已 gitignore |
|
||
| Playwright | `./.cache/ms-playwright` | 已 gitignore |
|
||
|
||
### 15.5 pnpm 构建脚本白名单
|
||
|
||
pnpm 11 默认拦截依赖的安装脚本；以下必须放行（与 scgf `pnpm-workspace.yaml` 一致）：
|
||
|
||
```yaml
|
||
# pnpm-workspace.yaml
|
||
packages:
|
||
- apps/*
|
||
- packages/*
|
||
allowBuilds:
|
||
bcrypt: true
|
||
sharp: true
|
||
onnxruntime-node: true
|
||
msgpackr-extract: true
|
||
```
|
||
|
||
> 若 pnpm 11 提示 `allowBuilds` 未知字段，改用 `onlyBuiltDependencies`（同上清单）。CI 以 `pnpm install --frozen-lockfile` 成功为准。
|
||
|
||
---
|
||
|
||
## 16 构建与部署
|
||
|
||
### 16.1 镜像
|
||
|
||
| 镜像 | 基础 | 内容 |
|
||
|---|---|---|
|
||
| `lingxi/web` | `nginx:1.29-alpine` | 构建后的 SPA + nginx 配置 |
|
||
| `lingxi/api` | `node:24.15.0-bookworm-slim` | api 构建产物 + prisma 运行时 |
|
||
| `lingxi/worker-*` | 同上 | 各自 worker 产物 |
|
||
|
||
- 构建阶段：`corepack enable` → `pnpm install --frozen-lockfile` → `pnpm --filter <pkg> build`；运行阶段只拷贝 `dist` + `node_modules`（pnpm deploy/`--prod`）。
|
||
- 非 root 用户运行；`NODE_ENV=production`。
|
||
- Node 镜像若暂无 `24.15.0-bookworm-slim` tag：锁定 `node:24-bookworm-slim` 的 digest，并在构建阶段执行 `node -v` 断言 `v24.15.0`，不通过则失败。
|
||
|
||
### 16.2 Compose（生产/联调）
|
||
|
||
```yaml
|
||
services:
|
||
web: { image: lingxi/web, ports: ["80:80", "443:443"] }
|
||
api: { image: lingxi/api, env_file: .env }
|
||
worker-image: { image: lingxi/worker-image, env_file: .env }
|
||
worker-platform: { image: lingxi/worker-platform, env_file: .env }
|
||
worker-ai: { image: lingxi/worker-ai, env_file: .env }
|
||
worker-export: { image: lingxi/worker-export, env_file: .env }
|
||
# PG/Redis 使用外部实例（已有/托管），不写入 compose
|
||
```
|
||
|
||
- 发布顺序：备份 → `prisma migrate deploy`（一次性 job）→ api → workers → web → 健康检查。
|
||
- 迁移采用 expand/contract，保证旧版本可回滚；镜像保留上一版。
|
||
- 备份：每日 `pg_dump` + WAL 归档；对象存储版本化；恢复演练每季度。
|
||
|
||
### 16.3 nginx 关键配置
|
||
|
||
| 路径 | 配置 |
|
||
|---|---|
|
||
| `/` | SPA，`try_files $uri $uri/ /index.html` |
|
||
| `/api/` | 反代 api:8300；`client_max_body_size 300m`；超时 300s |
|
||
| `/api/v1/events` | `proxy_buffering off; proxy_read_timeout 3600s;` |
|
||
| `/files/` | 反代 api（本地驱动）或直连对象存储（生产用签名 URL 跳过） |
|
||
|
||
---
|
||
|
||
## 17 版本治理
|
||
|
||
| 类别 | 策略 |
|
||
|---|---|
|
||
| Node/pnpm | 精确锁定；`.nvmrc` + `engines` + 镜像三处一致 |
|
||
| Playwright | 精确锁定；浏览器 revision 随包；升级需回归送审选择器 |
|
||
| 图像栈 | 精确锁定；升级需黄金样本 + 像素 diff 通过 |
|
||
| Prisma | 精确锁定 minor；升级需跑迁移与集成测试 |
|
||
| UI 库 | caret + lockfile；每月升级窗口 |
|
||
| 依赖 | `pnpm-lock.yaml` 提交；`pnpm audit --prod` 入 CI |
|
||
| 废弃 | 不保留 Electron/桌面端构建链 |
|
||
|
||
---
|
||
|
||
## 18 与评估文档的差异（需同步）
|
||
|
||
| 项 | 评估（ORM/UI 定稿前） | 本定稿 | 影响 |
|
||
|---|---|---|---|
|
||
| ORM | Sequelize 6（复用 scgf） | **Prisma 7.10.1**（模型/迁移重写） | **+8~12 人日**；总量 383~569 → **391~581**；首期 280~414 → **288~426** |
|
||
| UI CSS | Tailwind 3.4（dewu 验证） | **Tailwind 4.3.3 + Semi 2.104** | +1~3 人日集成验证（在 ±25% 内） |
|
||
| 运行时 | Node 24 LTS | **Node 24.15.0 精确** | 无 |
|
||
| 数据/缓存 | PG/Redis 由部署提供 | **复用开发机已有 Docker，不负责安装** | 省去部署工作 |
|
||
| 部署 | 单机 Compose | 同 | 公网安全加固 4~8 人日已列 |
|
||
| 对象存储 | S3 适配 | **local(dev)/OSS(prod)** | 同 |
|
||
|
||
> 评估文档已同步更新为 **391~581 人日 / 首期 288~426 人日**（rev.2）；本定稿以 Prisma + Tailwind 4 为准。
|
||
|
||
---
|
||
|
||
## 19 M0 必须验证的风险（Go/No-Go）
|
||
|
||
| 编号 | 风险 | 验证方式 | 通过标准 | 回退方案 |
|
||
|---|---|---|---|---|
|
||
| R1 | Semi 2.104 + Tailwind 4.3 + Vite 8 样式层叠冲突 | 建一个含 Table/Modal/Drawer/Form 的 Spike 页 | 组件样式正确、暗色/中文正常、`@layer` 顺序可控 | 回退 Tailwind 3.4.19 + Semi 2.104（dewu 已验证） |
|
||
| R2 | Prisma 7.10.1 + PG18 + Node 24.15 | 建 5 张表、迁移、seed、事务、uuidv7 默认值、adapter-pg 连接 | 迁移/回滚/连接池/类型生成全通过；`select uuidv7()` 返回 v7（本机已验证 PG18 支持） | 回退 Prisma 7.9.x 或评估 Drizzle（需重新评审） |
|
||
| R3 | sharp 0.32.6 / ag-psd 30.1 / canvas 0.1.97 在 Node 24 arm64 + Linux 镜像 | 本机 + Docker 各跑一次合成 | 输出一致、无崩溃 | 逐项升级并重跑黄金样本 |
|
||
| R4 | Playwright 1.64 在 macOS/Linux 行为差异 | 本机跑登录/送审空跑 | 选择器/上传可用 | 锁定 1.60（dewu 已验证） |
|
||
| R5 | Node 24.15.0 官方镜像 tag | `docker build` 构建 API 镜像 | `node -v` = 24.15.0 | 用 `node:24-bookworm-slim` + digest + 版本断言 |
|
||
| R6 | OSS SDK 选择（ali-oss vs S3 兼容） | 用测试 bucket 跑 put/sign/get | 签名 URL 可下载、分片上传可用 | 统一改用 S3 兼容网关 |
|
||
| R7 | Prisma 迁移 19 表的一次性搬迁 | 从 scgf 导出数据导入新库 | 行数/文件/命名对账通过 | 分批迁移 + 只读并行 |
|
||
|
||
---
|
||
|
||
## 20 明确不采用的技术与理由（ADR）
|
||
|
||
| 不采用 | 理由 |
|
||
|---|---|
|
||
| Sequelize 6 | 用户选择 Prisma；类型/迁移体验更好；代价是模型重写 +8~12 人日 |
|
||
| Tailwind 3 | 用户选择 Tailwind 4；需 M0 验证 Semi 共存 |
|
||
| Arco Design / shadcn/ui | 用户选择 Semi；Arco 与 scgf 页面绑定，shadcn 需自建后台组件层 |
|
||
| WebSocket | 任务进度单向，SSE 足够；少一套鉴权/心跳/广播实现 |
|
||
| Next.js | 内部 SPA，不需要 SSR/SEO；Vite SPA 更简单 |
|
||
| NestJS / Fastify | Express 5 可迁移 scgf 中间件；换框架收益低于成本 |
|
||
| MongoDB | 主数据强关系 + 事务 + 报表；PG 合适 |
|
||
| Redis 8 / PG 17 | 用户环境已固定 Redis 7 / PG 18 |
|
||
| K8s（首期） | 单机 Compose 足够；代码保持无状态，后续可迁移 |
|
||
| MinIO（开发必选） | 用户未提供；开发用 local 驱动，生产用 OSS |
|
||
| npm | 用户要求统一 pnpm |
|
||
| Electron | 桌面端停止演进 |
|
||
|
||
---
|
||
|
||
## 21 附录 A：`.npmrc` 与根配置
|
||
|
||
```ini
|
||
engine-strict=true
|
||
auto-install-peers=true
|
||
strict-peer-dependencies=false
|
||
resolution-mode=highest
|
||
```
|
||
|
||
> `auto-install-peers=true` 用于兼容 Semi/Tailwind 生态的 peer 依赖；锁定 lockfile 后再收紧。
|
||
|
||
## 22 附录 B：依赖清单（按包）
|
||
|
||
> 完整版本以 `pnpm-lock.yaml` 为准；下表为定稿基线。
|
||
|
||
| 包 | dependencies 摘要 |
|
||
|---|---|
|
||
| `apps/web` | react 19.3.1、react-dom 19.3.1、react-router-dom 7.18.5、@douyinfe/semi-ui 2.104.0、@remixicon/react 4.9.0、zustand 5.0.16、@tanstack/react-query 5.105.0、axios 1.21.0、react-hook-form 7.91.0、@hookform/resolvers 6.0.2、zod 4.6.7、recharts 3.10.1、dayjs 1.11.23、marked 18.1.2 |
|
||
| `apps/api` | express 5.3.0、@lingxi/db、@lingxi/shared、@lingxi/domain、@lingxi/storage、@lingxi/ai、bullmq 6.5.0、ioredis 6.0.0、jsonwebtoken 9.0.3、bcrypt 6.0.0、multer 2.5.0、zod 4.6.7、pino 10.4.0、pino-http 11.0.0、helmet 8.3.0、cors 2.8.6、compression 1.8.2、express-rate-limit 8.7.2、rate-limit-redis 6.0.2、archiver 8.0.0、exceljs 4.4.0、uuid 14.0.3、dotenv 18.0.9、prom-client 15.1.3、otplib 13.5.0 |
|
||
| `packages/db` | @prisma/client 7.10.1、@prisma/adapter-pg 7.10.1、pg 8.23.1 |
|
||
| `packages/domain` | zod 4.6.7、dayjs 1.11.23（纯逻辑，不依赖 DB/HTTP） |
|
||
| `packages/platform-dewu` | 原生 fetch（Node 24 内置）、playwright 1.64.1、zod 4.6.7 |
|
||
| `packages/storage` | @aws-sdk/client-s3 3.1160.0、@aws-sdk/s3-request-presigner 3.1160.0、ali-oss 6.23.0 |
|
||
| `packages/ai` | 原生 fetch、zod 4.6.7 |
|
||
| `apps/worker-image` | sharp 0.32.6、ag-psd 30.1.0、@napi-rs/canvas 0.1.97、fontkit 2.0.4、@imgly/background-removal-node 1.4.5、@lingxi/domain、@lingxi/storage |
|
||
| `apps/worker-platform` | playwright 1.64.1、@lingxi/platform-dewu、@lingxi/platform-vipshop、@lingxi/db |
|
||
| `apps/worker-ai` | @lingxi/ai、@lingxi/storage |
|
||
| `apps/worker-export` | archiver 8.0.0、exceljs 4.4.0、@lingxi/storage |
|
||
| 根 devDependencies | typescript 5.9.3、tsx 4.23.15、vite 8.3.5、@vitejs/plugin-react 6.1.2、tailwindcss 4.3.3、@tailwindcss/vite 4.3.3、@douyinfe/semi-vite-plugin 2.104.0、eslint 10.13.0、typescript-eslint 8.72.1、prettier 3.9.10、vitest 5.0.5、@vitest/coverage-v8 5.0.5、@testing-library/react 16.3.3、jsdom 30.1.3、playwright 1.64.1、pino-pretty 13.2.0、prisma 7.10.1 |
|
||
|
||
## 23 附录 C：待确认项
|
||
|
||
| 编号 | 问题 | 影响 | 建议 |
|
||
|---|---|---|---|
|
||
| C-01 | 生产 OSS 的 region/bucket/账号是否已就绪？ | 决定 `oss` 驱动配置与直传凭证 | M0 前确认 |
|
||
| C-02 | 是否有云 WAF/高防？还是仅 nginx 限流？ | 公网安全方案 | M0 前确认 |
|
||
| C-03 | CI 平台是 GitHub Actions 还是内网 GitLab？ | CI 配置模板 | M0 前确认 |
|
||
| C-04 | 生产是否为单台 Linux + Docker？ | Compose/备份/监控方案 | M0 前确认 |
|
||
| C-05 | 管理员 MFA 是否首期强制？ | 登录流程与 `otplib` 依赖 | 建议首期强制 |
|
||
| C-06 | Tailwind 4 + Semi 的 Spike 谁负责/何时完成？ | 前端开工前置 | M0 第 1 周 |
|
||
|
||
---
|
||
|
||
*定稿基于 2026-10-30 的开发机实测、pnpm registry 版本与两个参考项目源码；任何版本调整必须更新本文档与 lockfile。*
|