项目结构与运行边界

状态：初始化骨架已创建并完成版本基线锁定。本文描述仓库的代码归属、构建关系和本地运行边界；业务规则仍以项目交接、API 契约和数据模型文档为准。

1. 目录结构

atlas-seller-kit/
├── apps/                              # 可独立启动、构建和部署的入口
│   ├── web/                            # React + Vite 卖家工作台
│   ├── api/                            # NestJS：HTTP、鉴权、事务与任务创建
│   ├── worker/                         # BullMQ：Outbox 投递、媒体、AI、同步、发布
│   └── extension/                      # WXT 浏览器采集扩展
├── packages/                          # 跨应用的稳定复用单元
│   ├── contracts/                      # Zod 契约、DTO、共享类型
│   └── database/                       # SQL migrations、迁移/应用连接基础设施
├── infra/
│   ├── compose.yaml                    # local PostgreSQL、Redis、MinIO
│   └── README.md                       # 本地基础设施启动说明
├── docs/                               # 产品、架构、API 与评审记录
├── package.json                        # 根命令、Node/pnpm 版本约束
├── .nvmrc                              # 本地 Node 24 LTS 版本
├── pnpm-workspace.yaml                 # workspace 边界
├── turbo.json                          # 构建、检查、测试任务图
└── tsconfig.base.json                  # 最小共享 TypeScript 编译约定

apps 只能依赖明确的 packages，不能横向导入另一个应用的源码。这样 API、Worker 和扩展即使独立部署，也始终共享同一份契约。反过来，packages 不得依赖任何 apps。

2. 代码与服务关系图

flowchart TB
  subgraph Repository[Atlas Seller Kit · pnpm workspace]
    subgraph Applications[apps：部署与运行入口]
      WEB[web\nReact / Vite]
      API[api\nNestJS HTTP API]
      WORKER[worker\nBullMQ processors]
      EXT[extension\nWXT Collector]
    end

    subgraph Shared[packages：跨应用稳定边界]
      CONTRACTS[contracts\nZod · DTO · payload types]
      DB[database\nSQL migrations · DB access]
    end

    subgraph LocalInfra[infra/compose.yaml：本地依赖]
      PG[(PostgreSQL)]
      REDIS[(Redis)]
      MINIO[(MinIO)]
    end
  end

  WEB -->|HTTPS /api| API
  EXT -->|Bearer API request| API
  API --> CONTRACTS
  EXT --> CONTRACTS
  API --> DB
  WORKER --> DB
  API -->|transactional outbox| PG
  API --> REDIS
  WORKER -->|consume / retry| REDIS
  WORKER --> PG
  WORKER --> MINIO

3. 运行时责任与数据流

sequenceDiagram
  participant U as 用户
  participant E as 浏览器扩展
  participant W as Web
  participant A as API
  participant P as PostgreSQL
  participant R as Redis / BullMQ
  participant K as Worker
  participant O as MinIO / Kodo

  U->>E: 在来源商品页采集
  E->>A: 共享契约校验后的采集载荷
  A->>P: 同一事务写业务记录、operation、outbox event
  A-->>E: 采集记录 / 编辑入口
  K->>P: Dispatcher 领取未投递 outbox event
  K->>R: 投递或消费可重试任务
  K->>O: 下载、处理、转存素材
  K->>P: 保存任务状态、结果与错误
  U->>W: 查看进度、编辑、发布
  W->>A: 鉴权后的 HTTP 请求
  A->>P: SET LOCAL app.workspace_id 后读写

业务事实、审计、操作状态和 Outbox 只在 PostgreSQL 持久化；Redis/BullMQ 负责排队、限流和重试，不能成为唯一事实来源。local 使用 MinIO，staging/production 使用隔离的七牛 Kodo Bucket。

4. 依赖规则

位置	可以依赖	不应依赖
`apps/web`	`packages/contracts`、前端库	API/Worker 源码、数据库直连
`apps/api`	`packages/contracts`、`packages/database`	Web/扩展源码
`apps/worker`	`packages/contracts`、`packages/database`	Web/扩展源码、浏览器会话
`apps/extension`	`packages/contracts`	API 内部模块、ERP localStorage token
`packages/contracts`	Zod 等无运行环境依赖库	NestJS、React、数据库驱动
`packages/database`	PostgreSQL 驱动、迁移工具	HTTP/UI/平台适配逻辑

当前只抽取了已经确认会跨端复用的采集契约和数据库边界。认证、商品、定价或 Ozon 适配器尚不单独建共享包，等首个纵向闭环出现稳定复用关系后再提取，避免过早形成空壳“公共库”。

5. 本地开发入口

运行时基线：Node 24.20.0（见 .nvmrc）、pnpm 11.25.0、Web 8100、API 8200、扩展 dev server 8110（仅本地开发用）。Worker 是队列消费者，不对浏览器提供 HTTP 服务，因此没有端口号。

cp .env.example .env
pnpm install
pnpm infra:up       # PostgreSQL 18.6、Redis 7.4、MinIO
pnpm dev            # Web、API、Worker、Extension 并行 watch

常用验证命令：pnpm build、pnpm typecheck、pnpm format:check。首次实现数据库迁移执行器时，必须将 atlas_migrator 和 atlas_app_login 的连接串分开配置，并在集成测试中验证 RLS 隔离。

本地 Docker 镜像使用明确标签而非 latest；完整依赖版本表见技术与部署方案。

6. 接下来的实现顺序

在 packages/database 实现只接受 migrator 连接串的可重复 SQL migration runner，并导入已评审的 001_foundation.sql、002_product-domain.sql。
在 API 建立配置校验、认证、工作空间上下文和事务包装器；任何工作空间查询前固定 SET LOCAL app.workspace_id。
建立 operations、幂等请求和 Outbox Dispatcher 的第一个集成测试闭环。
再实现平台/门店、素材上传和 Web 对应页面；扩展仅在 API 采集入口稳定后接入实际解析器。

相关约束见：技术与部署方案、数据库安全、Outbox 与幂等、项目交接。

6.1 KiB Raw Blame History Unescape Escape