feat: 初始化项目
This commit is contained in:
R524809
@@ -10,6 +10,7 @@
|
||||
| 产品需求 | [`requirements/`](./requirements/) | 页面、流程、字段和待确认事项 |
|
||||
| 基础架构 | [`architecture/`](./architecture/) | 多租户、平台、门店、水印、物流和定价的数据设计及 DDL |
|
||||
| 商品领域设计 | [`product/`](./product/) | 已有的多 SKU 商品编辑页、领域模型与 API 草案 |
|
||||
| 项目结构 | [`architecture/project-structure.md`](./architecture/project-structure.md) | pnpm monorepo 的目录、依赖关系与本地运行边界。 |
|
||||
| 外部平台资料 | [`integrations/`](./integrations/) | Ozon Seller API 的整理资料与适配依据 |
|
||||
| 学习指南 | [`guides/`](./guides/) | 项目所用技术概念与设计原则的入门说明 |
|
||||
| HTTP API 设计 | [`api/`](./api/) | 可评审的服务端接口契约，按模块逐步补全。 |
|
||||
|
||||
@@ -0,0 +1,126 @@
|
||||
# 项目结构与运行边界
|
||||
|
||||
> 状态：初始化骨架已创建。本文描述仓库的代码归属、构建关系和本地运行边界；业务规则仍以项目交接、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. 本地开发入口
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
pnpm install
|
||||
pnpm infra:up # PostgreSQL、Redis、MinIO
|
||||
pnpm dev # Web、API、Worker、Extension 并行 watch
|
||||
```
|
||||
|
||||
常用验证命令：`pnpm build`、`pnpm typecheck`、`pnpm format:check`。首次实现数据库迁移执行器时，必须将 `atlas_migrator` 和 `atlas_app_login` 的连接串分开配置，并在集成测试中验证 RLS 隔离。
|
||||
|
||||
## 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)。
|
||||
@@ -16,6 +16,8 @@
|
||||
|
||||
不将旧项目的 FastAPI 服务作为新项目运行时依赖；旧项目的 Ozon 资料、计价规则、采集经验和前端技术路线可作为参考或选择性复用。
|
||||
|
||||
代码仓库采用 pnpm workspace monorepo：Web、API、Worker 与浏览器扩展位于独立 `apps/*`，跨端 API 契约和数据库迁移基础设施位于 `packages/*`。目录和依赖边界见 [项目结构与运行边界](./project-structure.md)。
|
||||
|
||||
## 2. 服务边界
|
||||
|
||||
```text
|
||||
|
||||
Reference in New Issue
Block a user