# 项目结构与运行边界

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

## 1. 目录结构

```text
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. 代码与服务关系图

```mermaid
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. 运行时责任与数据流

```mermaid
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 服务，因此没有端口号。

```bash
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`；完整依赖版本表见 [技术与部署方案](./technology-and-deployment.md)。

## 6. 接下来的实现顺序

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

相关约束见：[技术与部署方案](./technology-and-deployment.md)、[数据库安全](./database-security.md)、[Outbox 与幂等](./transactional-outbox-and-idempotency.md)、[项目交接](../project/HANDOFF.md)。