131 lines
6.1 KiB
Markdown
131 lines
6.1 KiB
Markdown
# 项目结构与运行边界
|
||
|
||
> 状态：初始化骨架已创建并完成版本基线锁定。本文描述仓库的代码归属、构建关系和本地运行边界；业务规则仍以项目交接、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)。
|