joey5628/atlas-seller-kit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新初始化交接文档

Browse Source
This commit is contained in:
R524809
2026-09-02 17:56:42 +08:00
parent 1a2caba2b3
commit 09e5207c83
3 changed files with 31 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/project-structure.md
+6 -2
View File
@@ -1,6 +1,6 @@
# 项目结构与运行边界 # 项目结构与运行边界
> 状态：初始化骨架已创建。本文描述仓库的代码归属、构建关系和本地运行边界；业务规则仍以项目交接、API 契约和数据模型文档为准。 > 状态：初始化骨架已创建并完成版本基线锁定。本文描述仓库的代码归属、构建关系和本地运行边界；业务规则仍以项目交接、API 契约和数据模型文档为准。
## 1. 目录结构 ## 1. 目录结构
@@ -107,15 +107,19 @@ sequenceDiagram
## 5. 本地开发入口 ## 5. 本地开发入口
运行时基线：Node 24.20.0（见 `.nvmrc`）、pnpm 11.25.0、Web `8100`、API `8200`。Worker 是队列消费者，不对浏览器提供 HTTP 服务，因此没有端口号。
```bash ```bash
cp .env.example .env cp .env.example .env
pnpm install pnpm install
pnpm infra:up # PostgreSQL、Redis、MinIO pnpm infra:up # PostgreSQL 18.6、Redis 7.4、MinIO
pnpm dev # Web、API、Worker、Extension 并行 watch pnpm dev # Web、API、Worker、Extension 并行 watch
``` ```
常用验证命令：`pnpm build`、`pnpm typecheck`、`pnpm format:check`。首次实现数据库迁移执行器时，必须将 `atlas_migrator` 和 `atlas_app_login` 的连接串分开配置，并在集成测试中验证 RLS 隔离。 常用验证命令：`pnpm build`、`pnpm typecheck`、`pnpm format:check`。首次实现数据库迁移执行器时，必须将 `atlas_migrator` 和 `atlas_app_login` 的连接串分开配置，并在集成测试中验证 RLS 隔离。
本地 Docker 镜像使用明确标签而非 `latest`；完整依赖版本表见 [技术与部署方案](./technology-and-deployment.md)。
## 6. 接下来的实现顺序 ## 6. 接下来的实现顺序
1. 在 `packages/database` 实现只接受 migrator 连接串的可重复 SQL migration runner，并导入已评审的 `001_foundation.sql`、`002_product-domain.sql`。 1. 在 `packages/database` 实现只接受 migrator 连接串的可重复 SQL migration runner，并导入已评审的 `001_foundation.sql`、`002_product-domain.sql`。
docs/architecture/technology-and-deployment.md
+15 -9
View File
@@ -4,20 +4,24 @@
## 1. 已确认技术选型 ## 1. 已确认技术选型
| 层级 | 选型 | 职责 | | 层级 | 选型 | 当前版本 / 镜像 | 职责 |
|---|---|---| |---|---|---|---|
| 前端 | React 19、TypeScript、Vite、Ant Design、React Router、Axios | 延续 `ozon-seller-kit/studio` 的前端技术路线，构建卖家工作台。 | | 前端 | React、TypeScript、Vite、Ant Design、React Router、Axios | React 19.2.8；TypeScript 7.0.2；Vite 8.2.2；Ant Design 6.6.2；Router 7.18.3；Axios 1.20.0 | 延续 `ozon-seller-kit/studio` 的前端技术路线，构建卖家工作台。 |
| 主后端 | NestJS、TypeScript | 认证、门店、商品/SKU、定价、平台适配、任务编排和 HTTP API。 | | 主后端 | NestJS、TypeScript | NestJS 12.0.1；TypeScript 7.0.2 | 认证、门店、商品/SKU、定价、平台适配、任务编排和 HTTP API。 |
| 关系数据库 | PostgreSQL | 业务事实来源：用户、隐藏工作空间、门店、商品、报价、任务记录和审计。 | | 关系数据库 | PostgreSQL | `postgres:18.6-alpine`（local） | 业务事实来源：用户、隐藏工作空间、门店、商品、报价、任务记录和审计。 |
| 缓存与队列 | Redis、BullMQ | 待执行任务、延迟/重试、进度和限流；不作为业务事实来源。 | | 缓存与队列 | Redis、BullMQ | `redis:7.4.11-alpine3.21`（local）；BullMQ 6.3.4 | 待执行任务、延迟/重试、进度和限流；不作为业务事实来源。 |
| 对象存储（本地） | MinIO | 本地开发存放图片和文件，使用 S3 兼容接口。 | | 对象存储（本地） | MinIO | `minio/minio:RELEASE.2025-09-07T16-13-09Z` | 本地开发存放图片和文件，使用 S3 兼容接口。 |
| 对象存储（生产） | 七牛云 Kodo | 生产及共享测试环境存放图片和文件。Kodo 的基础 S3 兼容能力用于上传、下载、删除和短时访问链接。 | | 对象存储（生产） | 七牛云 Kodo | 生产及共享测试环境存放图片和文件。Kodo 的基础 S3 兼容能力用于上传、下载、删除和短时访问链接。 |
| 运行与编排 | Docker、Docker Compose | 本地一键启动依赖；首期服务器部署 API、Worker、Redis 和反向代理。 | | 浏览器扩展 | WXT、React | WXT 0.21.4；`@wxt-dev/module-react` 1.2.2；React 19.2.8 | 在来源商品详情页运行采集器。 |
| 运行时与构建 | Node.js、pnpm、Turborepo、Prettier | Node 24.20.0；pnpm 11.25.0；Turbo 2.10.12；Prettier 3.9.6 | 固定本地/CI 运行时，管理 workspace、任务编排和格式校验。 |
| 运行与编排 | Docker、Docker Compose | Docker Compose local 基础依赖 | 本地一键启动依赖；首期服务器部署 API、Worker、Redis 和反向代理。 |
不将旧项目的 FastAPI 服务作为新项目运行时依赖；旧项目的 Ozon 资料、计价规则、采集经验和前端技术路线可作为参考或选择性复用。 不将旧项目的 FastAPI 服务作为新项目运行时依赖；旧项目的 Ozon 资料、计价规则、采集经验和前端技术路线可作为参考或选择性复用。
代码仓库采用 pnpm workspace monorepo：Web、API、Worker 与浏览器扩展位于独立 `apps/*`，跨端 API 契约和数据库迁移基础设施位于 `packages/*`。目录和依赖边界见 [项目结构与运行边界](./project-structure.md)。 代码仓库采用 pnpm workspace monorepo：Web、API、Worker 与浏览器扩展位于独立 `apps/*`，跨端 API 契约和数据库迁移基础设施位于 `packages/*`。目录和依赖边界见 [项目结构与运行边界](./project-structure.md)。
版本由根目录 `package.json`、`.nvmrc` 与 `infra/compose.yaml` 锁定；镜像不使用 `latest`。pnpm 11 启用供应链保护：仅允许 `esbuild` 执行安装构建脚本，`msgpackr-extract` 保持禁用。
## 2. 服务边界 ## 2. 服务边界
```text ```text
@@ -114,7 +118,9 @@ workspaces/{workspaceId}/
## 7. Docker 与首期部署 ## 7. Docker 与首期部署
本地 Docker Compose 至少编排：`web`、`api`、`worker`、`postgres`、`redis`、`minio`。前端开发也可单独使用 Vite 热更新，并将 `/api` 代理至本地 API。 当前仓库的 `infra/compose.yaml` 只编排本地基础依赖：`postgres`、`redis`、`minio`；`web`、`api`、`worker` 与 `extension` 通过 `pnpm dev` 在宿主机并行 watch。Web 默认监听 `8100`，API 默认监听 `8200`，Web 的 `/api` 代理目标为 `http://localhost:8200`；Worker 不监听 HTTP 端口。
后续若将本地应用进程也容器化，Compose 至少应覆盖：`web`、`api`、`worker`、`postgres`、`redis`、`minio`。前端开发也可单独使用 Vite 热更新，并将 `/api` 代理至本地 API。
首期云端 Docker Compose 编排：`api`、`worker`、`redis`、`reverse-proxy`；PostgreSQL 使用云托管实例，图片使用七牛 Kodo。每个环境使用独立 `.env`/密钥管理配置，密钥不提交 Git、不进入前端构建产物和日志。 首期云端 Docker Compose 编排：`api`、`worker`、`redis`、`reverse-proxy`；PostgreSQL 使用云托管实例，图片使用七牛 Kodo。每个环境使用独立 `.env`/密钥管理配置，密钥不提交 Git、不进入前端构建产物和日志。
docs/project/HANDOFF.md
+10 -8
View File
@@ -6,7 +6,9 @@
这是一个全新的云端产品，不是 `ozon-seller-kit` 的本地版重构。目标用户可拥有多个门店，每个门店只能绑定一个平台；平台自身可支持多个市场、国家、语言和币种。因此语言、币种、类目和发布规则不能写死为 Ozon 或中文/俄文。 这是一个全新的云端产品，不是 `ozon-seller-kit` 的本地版重构。目标用户可拥有多个门店，每个门店只能绑定一个平台；平台自身可支持多个市场、国家、语言和币种。因此语言、币种、类目和发布规则不能写死为 Ozon 或中文/俄文。
当前项目还没有业务代码、数据库、部署或依赖。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验，但必须先适配多租户和云端边界。 当前已完成 pnpm monorepo 初始化：包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享 API 契约、数据库包、本地基础设施 Compose 与依赖锁文件。API 仅实现健康检查，Web/Worker/扩展仅有启动骨架；尚未实现业务模块、迁移执行器、数据库 schema、鉴权或实际部署。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验，但必须先适配多租户和云端边界。
当前运行时基线：Node 24.20.0、pnpm 11.25.0、PostgreSQL 18.6、Redis 7.4.11、MinIO `RELEASE.2025-09-07T16-13-09Z`；Web 默认端口为 `8100`，API 默认端口为 `8200`，Worker 无 HTTP 端口。完整目录、依赖边界与版本表见 [`architecture/project-structure.md`](../architecture/project-structure.md) 和 [`architecture/technology-and-deployment.md`](../architecture/technology-and-deployment.md)。
## 2. 已确认产品决策 ## 2. 已确认产品决策
@@ -54,7 +56,7 @@ User → Workspace → Membership / Role
## 5. 已冻结的第一阶段 API 契约 ## 5. 已冻结的第一阶段 API 契约
第一阶段 HTTP API 的接口范围已讨论完成，当前状态为**设计冻结、尚未实现**。后续编码以 [`docs/api/`](../api/README.md) 为唯一 HTTP 契约来源；旧 [`product/api.md`](../product/api.md) 仅作历史背景，不能作为实现依据。 第一阶段 HTTP API 的接口范围已讨论完成，当前状态为**设计冻结、业务接口尚未实现**。仓库已有 NestJS API 启动骨架及 `GET /health`，它不构成任何已实现的业务契约。后续编码以 [`docs/api/`](../api/README.md) 为唯一 HTTP 契约来源；旧 [`product/api.md`](../product/api.md) 仅作历史背景，不能作为实现依据。
- 覆盖账户认证、平台/门店、水印与素材、定价、浏览器采集/采集箱、商品编辑/首次发布、在线商品读取与同步。 - 覆盖账户认证、平台/门店、水印与素材、定价、浏览器采集/采集箱、商品编辑/首次发布、在线商品读取与同步。
- 所有接口遵循统一鉴权、工作空间隔离、页头平台上下文、金额字符串、错误格式、`Idempotency-Key`、`If-Match` 和异步 `operation` 约定。 - 所有接口遵循统一鉴权、工作空间隔离、页头平台上下文、金额字符串、错误格式、`Idempotency-Key`、`If-Match` 和异步 `operation` 约定。
@@ -65,13 +67,13 @@ User → Workspace → Membership / Role
## 6. 下一步建议 ## 6. 下一步建议
下一步进入项目初始化与实现准备，而不是继续扩大 API 范围： 项目初始化已完成；下一步进入实现准备，而不是继续扩大 API 范围：
1. 创建 NestJS 后端、React 前端、迁移工具、Redis/BullMQ 和本地 Docker Compose 骨架。 1. 以 `001_foundation.sql`、`002_product-domain.sql` 建立可重复执行的迁移执行器，并按数据库角色/RLS 约束验证本地环境。
2. 以 `001_foundation.sql`、`002_product-domain.sql` 建立可重复执行的迁移，并按数据库角色/RLS 约束验证本地环境。 2. 在 API 建立配置校验、认证、工作空间上下文和事务包装器；任何工作空间查询前固定 `SET LOCAL app.workspace_id`。
3. 在开始商品编辑/在线同步模块前，先关闭评审文档中的 P1 事项：同商品归属约束、未映射属性持久化、乐观锁 Repository 规则、平台能力 Schema；并确认在线商品归档策略和 Client ID 编辑边界。 3. 建立 `operations`、幂等请求和 Outbox Dispatcher 的第一个集成测试闭环。
4. 优先实现账户、平台上下文、门店、素材上传、操作任务、幂等/Outbox Dispatcher 的纵向最小闭环，再接入采集箱和商品编辑。 4. 在开始商品编辑/在线同步模块前，关闭评审文档中的 P1 事项：同商品归属约束、未映射属性持久化、乐观锁 Repository 规则、平台能力 Schema；并确认在线商品归档策略和 Client ID 编辑边界。
5. 为浏览器采集准备真实多 SKU 解析测试集，并继续限定 Ozon Seller 网页观察实验的字段口径，见 [`requirements/collector-browser-extension.md`](../requirements/collector-browser-extension.md)。 5. 优先实现账户、平台上下文、门店、素材上传的纵向最小闭环，再接入采集箱和商品编辑；浏览器扩展仅在采集 API 稳定后实现实际解析器。
## 7. 文档导航 ## 7. 文档导航