feat: 方案设计、数据库和接口设计基本完成

This commit is contained in:
R524809
2026-09-02 14:47:18 +08:00
parent a3fe066a5f
commit 04c94e75db
30 changed files with 3305 additions and 122 deletions
@@ -46,7 +46,7 @@ Redis 是高速的临时基础设施;BullMQ 使用 Redis 保存队列中的任
实现要求:
1. 所有长任务先在 PostgreSQL 创建任务记录,再在事务提交后投递队列;后续实施时使用 outbox 模式避免“数据库已提交但任务未投递”的遗漏。
1. 所有长任务在同一 PostgreSQL 事务中创建业务任务/`operation` 和 `outbox_events`;事务提交后由独立 Dispatcher 投递 BullMQ,避免“数据库已提交但任务未投递”。详见 [`transactional-outbox-and-idempotency.md`](./transactional-outbox-and-idempotency.md)。
2. 任务必须幂等:相同 SKU 的一次发布任务重试,不得重复创建平台商品。
3. 重试必须有次数上限、指数退避和可见错误;Ozon 等第三方 API 需按店铺/API 限额控制并发。
4. Redis 可丢失或重建,Worker 应能根据 PostgreSQL 中的未完成任务恢复投递;业务结果不只存在于 Redis。
@@ -102,6 +102,8 @@ workspaces/{workspaceId}/
不能把生产数据库作为开发数据库,也不建议所有日常开发直接共用同一云端数据库。数据库结构通过迁移文件保持一致;演示数据通过版本化 seed 脚本保持一致。迁移顺序必须是 local → staging → production,并在生产前备份和验证回滚方案。
数据库权限分为迁移角色与应用角色:迁移角色拥有表并只在部署迁移时使用;API/Worker 的应用登录角色只获业务表所需的 DML 权限,不拥有表且没有 `BYPASSRLS`。RLS 策略使用每个事务设置的 `app.workspace_id`;业务表启用并强制 RLS。具体初始化和权限清单见 [`database-security.md`](./database-security.md)。
## 6. AI 能力边界
首期 AI 智能规划、文案和生图均通过 Provider Adapter 调用云模型 API。NestJS 负责权限、上下文组装、结构化结果校验、任务状态和人工确认;模型不得直接改价、发布或修改门店数据。
@@ -115,3 +117,9 @@ workspaces/{workspaceId}/
首期云端 Docker Compose 编排:`api`、`worker`、`redis`、`reverse-proxy`;PostgreSQL 使用云托管实例,图片使用七牛 Kodo。每个环境使用独立 `.env`/密钥管理配置,密钥不提交 Git、不进入前端构建产物和日志。
在规模、可用性或多机部署出现明确瓶颈前,不引入 Kubernetes。
## 8. Ozon Seller 浏览器会话边界
一期浏览器插件可以在用户已登录的 `seller.ozon.ru` 标签页内,以同源请求调用已列白名单的四个网页内部接口,保存净化后的观察结果。该模式使用浏览器自动附带的会话 Cookie,但不提取完整 Cookie、不上传、不在 Atlas 保存,也不能交给云端 Worker 执行。
未来若要支持加密保存浏览器 Cookie,必须作为独立的二级实验能力:按门店验证会话归属,使用信封加密和可撤销的专用密钥记录,任务队列仅传密钥记录 ID,并逐接口限制用途。此类 Cookie 会话不替代官方 Seller API 的发布、库存或状态同步凭据。