docs: 更新初始化交接文档
This commit is contained in:
R524809
@@ -1,6 +1,6 @@
|
||||
# 项目结构与运行边界
|
||||
|
||||
> 状态：初始化骨架已创建。本文描述仓库的代码归属、构建关系和本地运行边界；业务规则仍以项目交接、API 契约和数据模型文档为准。
|
||||
> 状态：初始化骨架已创建并完成版本基线锁定。本文描述仓库的代码归属、构建关系和本地运行边界；业务规则仍以项目交接、API 契约和数据模型文档为准。
|
||||
|
||||
## 1. 目录结构
|
||||
|
||||
@@ -107,15 +107,19 @@ sequenceDiagram
|
||||
|
||||
## 5. 本地开发入口
|
||||
|
||||
运行时基线：Node 24.20.0（见 `.nvmrc`）、pnpm 11.25.0、Web `8100`、API `8200`。Worker 是队列消费者，不对浏览器提供 HTTP 服务，因此没有端口号。
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
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 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`。
|
||||
|
||||
@@ -4,20 +4,24 @@
|
||||
|
||||
## 1. 已确认技术选型
|
||||
|
||||
| 层级 | 选型 | 职责 |
|
||||
|---|---|---|
|
||||
| 前端 | React 19、TypeScript、Vite、Ant Design、React Router、Axios | 延续 `ozon-seller-kit/studio` 的前端技术路线，构建卖家工作台。 |
|
||||
| 主后端 | NestJS、TypeScript | 认证、门店、商品/SKU、定价、平台适配、任务编排和 HTTP API。 |
|
||||
| 关系数据库 | PostgreSQL | 业务事实来源：用户、隐藏工作空间、门店、商品、报价、任务记录和审计。 |
|
||||
| 缓存与队列 | Redis、BullMQ | 待执行任务、延迟/重试、进度和限流；不作为业务事实来源。 |
|
||||
| 对象存储（本地） | MinIO | 本地开发存放图片和文件，使用 S3 兼容接口。 |
|
||||
| 层级 | 选型 | 当前版本 / 镜像 | 职责 |
|
||||
|---|---|---|---|
|
||||
| 前端 | 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 | NestJS 12.0.1；TypeScript 7.0.2 | 认证、门店、商品/SKU、定价、平台适配、任务编排和 HTTP API。 |
|
||||
| 关系数据库 | PostgreSQL | `postgres:18.6-alpine`（local） | 业务事实来源：用户、隐藏工作空间、门店、商品、报价、任务记录和审计。 |
|
||||
| 缓存与队列 | Redis、BullMQ | `redis:7.4.11-alpine3.21`（local）；BullMQ 6.3.4 | 待执行任务、延迟/重试、进度和限流；不作为业务事实来源。 |
|
||||
| 对象存储（本地） | MinIO | `minio/minio:RELEASE.2025-09-07T16-13-09Z` | 本地开发存放图片和文件，使用 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 资料、计价规则、采集经验和前端技术路线可作为参考或选择性复用。
|
||||
|
||||
代码仓库采用 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. 服务边界
|
||||
|
||||
```text
|
||||
@@ -114,7 +118,9 @@ workspaces/{workspaceId}/
|
||||
|
||||
## 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、不进入前端构建产物和日志。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user