R524809
29 KiB
Atlas Seller Kit 深度审查报告
审查日期：2026-10-08。项目：/Users/joey-xd/sites/seller-store/atlas-seller-kit。审查版本：06dbd81（2026-10-07），审查前后 Git 工作区均干净，未修改项目。
结论与下一步选择
建议现在进入小批量上品运营，只修影响首批可售、价格正确和收费安全的问题。不要再以“完善 ERP”为开始经营的前提。
代码已具备完整的商品准备工作台：浏览器采集 → 采集箱 → SPU/SKU 草稿 → AI 文案与类目建议 → 图片处理/生图 → 定价确认 → 发布预检 → Ozon 导入与图片状态确认 → 在线商品同步。工程基础明显超过“前端页面加几个模型 API”的阶段，能够作为 AI 全栈项目经历。
但它的准确定位是商品采集、编辑和首次发布工具。当前没有完整的选品决策、库存写入、订单履约、退款和实际利润闭环。商品导入成功并不意味着可售，也不能证明能够盈利。继续打磨界面和生图功能不会解决这些经营不确定性。
对个人自用：已适合受控的小批量验证。对公开收费 SaaS：任务恢复、费用控制、安全与部署仍有明显缺口，不建议直接开放注册并推广。
不提供一个笼统的“完成度 85%”：商品准备、可售状态、商业验证和生产运维的分母不同，合成数字容易误导。
1. 本次实际验证范围
已读取根 README、工作约定、交接记录、协作契约、依赖与配置、路由与关键页面、采集扩展、认证/权限、商品与定价服务、AI 与图片 Worker、发布/同步、数据库迁移、任务调度和测试。核对真实 .env 时仅检查配置项是否存在及少量非秘密枚举；没有输出密钥值。未进行依赖漏洞联网审计。
所有编译与测试在当前会话 work/ 下的隔离副本执行，复用本机已安装依赖，没有复制真实 .env、安装新依赖或修改原项目。默认 Node 为 22.15.0；检查改用本机自带 Node 24.19.0，略低于仓库声明的 24.20.0 下限。因此这些结果不是对严格声明运行时的一次完整验收。没有升级运行时。
| 实际检查 | 结果 | 边界 |
|---|---|---|
| contracts / database 编译 | 通过 | 先构建共享包，再检查应用 |
| API 源码与测试类型检查、Worker/Web/扩展类型检查 | 全部通过 | 不代表数据库与远端配置有效 |
| API / Worker / Web / Chrome MV3 扩展构建 | 全部通过 | Web 有大包告警 |
| API 单元测试 | 17 文件、77 项通过 | 未运行数据库集成与 HTTP 端到端测试 |
| Worker 离线测试 | 67 项通过 | 排除数据库集成文件；模型/平台使用模拟调用 |
| 扩展解析与载荷测试 | 22 项通过 | 不是当前真实网站登录态采集验收 |
| 针对恢复/脱敏的额外模拟 | 3 项复现 | 文案 running 重投、队列丢失后投递、供应商原文 |
合计 166 项既有离线测试通过。额外 3 项模拟确认了报告中的缺口，不表示缺陷已修复。
没有连接真实数据库进行迁移或修改数据；没有启动/重启 API、Worker、Web，没有浏览器登录验收；没有调用收费模型、写入 Ozon 或变更七牛。历史文档中的真实验收记录单独标为历史证据。
检查中曾遇到共享包旧产物与隔离副本缓存目录权限问题，调整副本依赖及缓存目录后通过，不能把这些中间失败算作现行源码编译缺陷。commission-import.test.ts 顶层强制读取真实 .env，包含数据库集成，首次尝试因隔离副本无 .env 而失败；随后明确排除，77 项单元测试独立通过。
2. 功能清单：已实现、有限实现与未实现
| 能力 | 代码状态 | 关键证据与限制 |
|---|---|---|
| 注册/登录/刷新/资料/密码 | 已实现 | apps/api/src/auth/、Web settings 与 session；短期令牌、刷新轮换、认证限流 |
| 个人工作空间、多店铺 | 已实现 | Workspace Guard、stores 服务；首期每用户选一个个人空间，不是完整团队协作产品 |
| 1688、淘宝、天猫、Ozon 采集 | 已实现 | apps/extension/lib/source-parsers.ts:15、后台与 content scripts；依赖页面结构，淘宝/天猫样本覆盖弱于 1688 |
| 采集箱、来源资料、素材转存 | 已实现 | apps/api/src/collection/collection.service.ts、apps/worker/src/collection-assets.ts；不支持 HLS 转存 |
| 商品/SKU 草稿与平台属性 | 已实现 | 商品编辑页面、商品服务、contracts；SPU/SKU 继承、属性 schema、版本冲突和人工确认 |
| DeepSeek 文案与类目建议 | 已实现 | product-ai.service.ts 创建任务/快照/Outbox；Worker 生成俄文及中文对照、类目选择、货号规则、包装证据验证 |
| Ozon 必填属性全自动填写 | 未完整实现 | 动态属性加载与人工填写已实现；不能把 AI 类目/标题生成宣传成全部属性自动完成 |
| 单图编辑、扩图、水印、套图 | 已实现 | API media 模块、Worker media-ai-edit.ts、image-suite-plan.ts；套图支持规划、逐张任务、取消和失败部分重试 |
| GPT-Image-2 接入 | 已实现供应商适配 | media-ai-edit.ts:212 使用模型字符串，通过 Pcore 异步接口调用；不是直接验证了 OpenAI 官方接口或供应商底层模型身份 |
| SKU 试算、利润预估、确认报价 | 已实现 | 服务端 Decimal 引擎、不可变报价、保存确认、佣金导入、费率审核；试算输入与真实账单一致性仍待业务核对 |
| 首次 Ozon 发布 | 已实现 | 发布操作、不可变快照、预检、Outbox、Worker import/poll/reconcile；每批最多 50 SKU |
| 图片交付与缺图提示 | 已实现 | checksum 校验、独立发布副本、私有 HTTPS、图片状态查询；支持 imported 后继续检查图片 |
| 在线商品同步/状态浏览 | 已实现 | online-products API/Web、Worker 同步与映射；失败不冒充成功全量，连续未见归档 |
| 在线商品全面更新、库存写入、订单履约 | 未发现完整实现 | 当前同步与详情主要读取；首次发布明确要求到 Ozon 后台设置库存 |
| 选品研究、需求/竞争/销售验证 | 未发现完整实现 | 采集是资料输入工具，缺少销量需求、供应链质量和毛利实证闭环 |
| 多平台发布、团队协作、计费 SaaS | 架构预留/未完整实现 | 通用模型存在，现行发布具体落到 Ozon；没有证据支持这些能力已经上线 |
当前路由直接连接真实业务页面，PagePlaceholder.tsx 没有发现业务调用。不能沿用根 README 的“其余页面占位”结论；README 明显落后于现行代码。路由证据、旧 README。
3. 关键链路与质量判断
3.1 数据与权限：基础扎实，仍须数据库实测
API 先验证用户，再从 membership 确认个人工作空间，不信任客户端随意传入租户 ID；每个工作空间事务设置 app.workspace_id，应用事务降权为 atlas_app。迁移中大量业务表使用复合外键、唯一约束及 FORCE RLS。系统管理员权限实时查库，撤销不依赖 JWT 到期。
这比仅在请求中增加 workspace_id 更完整。但本次没有验证实际数据库角色、当前迁移账本和跨租户运行结果，不能宣布所有表均已安全验收。
证据：数据库事务、工作空间 Guard、管理员 Guard、发布 RLS。
仓库有 62 个 SQL 迁移。执行器按文件 checksum 防止历史迁移被改写、单文件原子提交，方向正确；没有看到跨迁移进程的全局锁。单机串行部署可暂不改，未来多人/自动部署时要限制并行迁移。
3.2 前后端与商品保存：边界清晰，维护成本正在上升
共享 contracts 使用 Zod、严格 TypeScript；API/Worker 与 Web 分离，耗时任务不直接压在 HTTP 上。商品、SKU、平台 profile 和报价分别建模，草稿保存与 AI 回填不是同一次写入。发布任务冻结输入，后续页面编辑不会悄悄改写已经排队的发布内容。版本冲突与幂等机制有实现。
但商品服务约 2,588 行，商品编辑页约 1,814 行，定价服务约 867 行。现阶段改动涉及大量表单继承/轮询/保存状态，回归成本高。建议只随具体缺陷提取保存、AI 回填、发布状态等独立职责，不做一次性重构。
3.3 AI：是有工程边界的工作流，可靠性与费用仍未闭环
DeepSeek 请求要求 JSON，设超时、有限重试，关闭思考以保留输出预算；对文案语言/标签、候选类目和包装证据有业务校验。模型没有获得直接改价或上架权限。套图规划与生图异步执行，重试代次防止旧结果污染新任务。这些均有实际代码及离线测试支持。
业务质量仍不能用“JSON 合法”或“含俄文字母”证明：标题是否地道、分类是否正确、卖点是否真实、图片是否改变实物、SKU 是否串款，需要标注样本和人工验收。目前更适合描述为 AI 商品工作流/AI 应用系统；没有必要为了履历重新包装成自主 Agent。
DeepSeek 返回 usage，但普通文案任务没有把它写入已有 token_usage 字段；套图规划会保存总 token，生图费用和全链路预算没有看到闭环。图像单次任务 20 张的上限不能替代按人/工作空间的费用上限。
证据：生成与任务保存、模型调用、token 字段、套图用量保存。
3.4 任务与容错：发布谨慎，所有任务未达到同一恢复水平
Outbox 在业务事务中创建，Dispatcher 用 SKIP LOCKED 与租期认领，BullMQ jobId 固定为 event ID，最多 5 次指数退避。发布 Worker 有独立租期、提交前货号查询、受理不确定时对账，避免盲目重新导入。图片查询与商品导入分开确认，能保留缺图警告。
但是“使用了 Outbox/BullMQ”不能等于“任意崩溃都能恢复”。具体缺口见下一节。当前公共业务队列 concurrency 为 5，目录有独立队列；没有看到店铺/API 维度完整的主动限速，仅处理平台 429 等响应。首批少量 SKU 可控，暂不需要拆更多队列或服务。
证据：Dispatcher、发布租期、图片结果确认、队列分工。
3.5 密钥、日志与存储：有保护设计，也存在具体遗漏
门店 API Key 使用 AES-256-GCM 密文、随机 nonce 和 HMAC 指纹；Outbox 通常只带任务/记录 ID。refresh Cookie 为 HttpOnly，生产 Secure，令牌可轮换。.env 被忽略且当前未跟踪。API 有 Helmet、请求大小限制、请求 ID、字段名递归日志脱敏与认证限流。
需要区分：AppLogger 的对象字段脱敏不会自动清洗任意字符串/URL；HTTP 日志记录 originalUrl，未来一旦查询参数携带秘密会被直接记录。Worker 日志也没有完全统一为相同的结构化脱敏管道。
扩展为登录互操作把短期 access token 镜像到 Web localStorage，这是项目已明确接受的取舍，不是误读为全部令牌都仅在内存。当前不应扩大它；公开部署前验证前端 CSP 和 XSS 防护，API 的 Helmet 配置不能替代 Web 静态站点的响应头。
4. 具体问题、证据与影响
A. 首单前必须确认的经营与配置问题（P0）
A1：首次导入不提交库存，实际可售闭环需人工完成。 Worker 的发布字段明确不包含库存/仓库；界面也写明库存在 Ozon 后台设置。没有库存、审核或可见性条件未满足时，导入成功无法产生订单。最小方案是每批上品后按后台清单补库存、配送与售价，检查实际可见性；暂不开发库存模块。请求映射、界面说明。
A2：按划线价提交 price，预期实际售价依赖后续后台操作。 API 明确使用 listing.list_price；10 月 4 日交接说明这是维护者已确认的业务规则，不能把它当作未经授权的程序 bug。其后果是忘记调整/配置实际成交价时，预估利润和转化依据可能与线上不一致。首批必须核对买家端价格或后台生效售价，不必先改公式。冻结价格、提示。
A3：草稿费率默认允许生产报价，报价确认不等于费率已审核。 draftPricingEnabled 在 auto 时仅排除 test，production 同样允许；这是现有业务选择。首批可以人工保守报价，但必须核对选用物流、佣金档位、重量尺寸、汇率和其他扣费，把不确定成本显式预留。无法取得真实费用依据的商品不要批量铺货。本次未读真实账单或当前费率数据，不能确定哪些卡已审核。默认行为、定价引擎。
A4：根 .env 与历史七牛发布验收存在配置差异，需要核实真实进程配置来源。 静态根 .env 为 development；未显式设置七牛 provider/交付域名或首次发布开关，AI 相关 key 已存在。代码 fallback 是本地 MinIO，但发布图片必须走七牛。实际进程可能有外部环境变量覆盖；本次未读取运行进程环境，不能断言现有服务配置错误。最小方案是只读展示有效 provider、发布开关、下载域名与环境名称，不展示密钥；确认使用七牛的商品素材和当前 Worker 配置一致。Worker 配置、交付硬约束。
B. 可靠性、费用与安全缺口（P1；公开提供服务前提升为阻断项）
B1：文案任务在 Worker 中断后可能永久 running。已离线复现。 任务先提交 running，再远端调用；重复执行只接受 queued，遇到 running 直接返回。进程在两步之间崩溃，BullMQ 重投也不会恢复；主 Worker 终态失败处理未覆盖文案任务。素材转存同样只认领 queued，部分中断状态需要检查。最小修复：领取租期/attempt 标识、过期任务允许重新认领或明确失败、结果回写校验处理权；先保障状态可解释，不必承诺恰好一次收费。文案门槛、素材认领、失败处理。
B2：Redis 丢失后，已 dispatched 事件没有完整恢复路径。模拟复现。 Dispatcher 只选 pending/过期 dispatching，入队后标 dispatched；若队列丢失而业务未终态，启动代码没看到扫描此类业务任务重新投递的机制。Compose 也未给 Redis 配持久卷/AOF。最小修复：Redis 持久化 + 受控未完成任务对账/重投；重投必须尊重发布的 submitting/reconciling 与生图供应商 ID，不能把所有任务简单重置 queued。认领过滤、标记已投递、启动流程、Redis 配置。
B3：生图在供应商受理、任务 ID 落库之间存在重复收费窗口。静态推断，未触发真实调用。 外部 POST 成功后才保存 provider_task_id；响应丢失或保存失败，自动重试仍见空 ID，会重新提交。没有看到供应商幂等键、提交租期或“不确定受理”对账状态。并发事件也没有跨外部调用的独占处理权。最小修复：记录提交 attempt；支持供应商幂等键时复用稳定 key，否则受理不确定进入显式状态，避免自动重复 POST，提示人工核对。不要为了此事改成 Agent。提交与保存。
B4：供应商错误原文未脱敏，并可返回页面。已用虚假 token 复现。 rawResponse 仅截断长度；failure_detail 的脱敏不覆盖 provider_error_raw。原文落入 operations，任务列表 API 返回，Web 以 pre 展示。若供应商回显凭据或签名链接，就扩大秘密暴露面。没有证据证明当前真实密钥已泄露，也不是已证明的跨租户越权。最小修复：解析并白名单提取错误 code/message、清洗 URL/Bearer/敏感字段；删除安全需求之外的原文，旧数据按受控方式清理。原文保存、数据库写入、API 返回、页面展示。
B5：采集素材下载存在 DNS 校验与实际连接分离的 SSRF 风险。静态风险，未进行攻击验证。 先 lookup 检查，再 fetch 重新解析，且 IPv6 映射/保留地址分类不完整。相比之下，网络图片导入用固定已校验地址连接。最小修复是复用该下载边界，让校验地址与连接地址一致，每次重定向重新校验；公开接受用户输入 URL 前处理。采集下载、更严谨下载实现。
B6：用量、预算、取消的经营语义不完整。 普通文案 usage 未持久化；没有完整生图成本账本/每 workspace 额度。取消主要改变本地状态并停止应用结果，不代表供应商取消或退款。先做按任务记录用量/估算成本、提交前张数×估算费用确认、日预算和供应商余额提醒。估算不能写成实际结算金额。文案保存、取消实现。
C. 可在运营之后做的改进（P2）
- README 和待决列表存在旧状态，交接记录很长、同能力描述前后不一致。只更新一份当前能力表、配置说明和待验收列表，不继续堆新文档。
- 根
lint运行 Turbo，但应用未定义 lint 脚本；不能把执行成功解释成代码经过 lint。Web 无成体系的自动交互回归；建议针对“保存后刷新仍在、AI 不覆盖未确认值、报价失效、发布结果恢复”补 3–5 条关键测试。 - Web 构建主包约 1,971 kB、gzip 621 kB；路由静态导入较多。先按系统管理与商品编辑路由延迟加载，是否继续优化取决于实际网络下首屏表现。构建告警不是首单阻断。
- 素材转存先上传，再按 checksum 查询重复项，发现已有素材时新上传对象未关联，可能产生孤儿对象。先查已有对象、冲突后清理或安排孤儿清理；单人小量暂不紧急。去重位置。
- 本地 Compose 发布 PostgreSQL/Redis/MinIO 端口，没有限定 loopback，Redis 无密码；文件明确属于开发环境，不应直接用于公网。云端应用编排、备份恢复演练和 CI 在仓库未发现完整实现。公开服务前补齐，个人本地运营先确认端口不外露即可。
/ready只测数据库，无法反映队列/Worker 是否健康。先监控最老 queued/running 任务年龄、最近 Worker 心跳和失败数，不引入大型观测平台。ready。
5. 商业完成度与真实证据
| 层次 | 判断 |
|---|---|
| 商品准备和编辑 | 实现较完整，已具备受控试用条件 |
| 首次平台导入 | 代码链路完整，仓库有真实 SKU 导入的历史记录 |
| 跨境图片交付 | 10 月 7 日记录了真实失败、全球加速调整与三图恢复；不是本次在线重验 |
| 审核通过、有效库存、配送和实际售价 | 需逐商品后台/买家端确认，本次未验证 |
| 首单、履约、真实毛利与复购 | 没有本次可核验数据，不能由工程质量推导 |
| 多用户稳定生产运行 | 尚缺费用、故障恢复与部署验收 |
关键历史材料：2026-10-07 图片交付诊断。它记载 Ozon imported 后出现图片抓取失败，调整七牛全球覆盖后，通过专用图片接口恢复一主图加两附图并核对顺序和像素。这比“接口返回成功”更有价值，也说明问题来自真实集成。但单 SKU 修复不能推广为所有商品、所有区域或当前配置均已通过。
接近首单时，最可能需要处理的是：库存/审核/可见性、成交价、物流与佣金依据、供应链交期和商品资料真实性。选品销量、采购与履约经验不能由增加技术模块替代。
6. 最小改进计划与预计投入
投入按你熟悉现有代码、AI 辅助实现估计，单位为工程工作日（约 6–8 小时），不包含平台审核、实际成交或结算等待；不同风险可能共用实现，勿机械累加工期。
| 优先级 | 最小交付 | 预计投入 | 验收条件 |
|---|---|---|---|
| P0 | 首批 3–5 SKU 的可售核对清单、配置核实、价格/成本人工复核 | 0.5–1.5 天，主要是业务操作 | 后台库存/配送/审核/有效售价与目标一致，图片完整可见 |
| P1 优先 | 生图原文脱敏和提交不确定时禁止盲目重复收费 | 1–2 天 | 假 token 不出 API/数据库结果；模拟 POST 后断连不会自动再付费提交 |
| P1 | 文案任务过期恢复、终态收尾；顺带检查素材 running | 1–2 天 | 在模型调用前后模拟中断，任务可恢复或明确失败，无永久 running |
| P1 | 用量记录、生成前估算、每日软预算/硬上限 | 0.5–1.5 天 | 能回答每个商品用了多少、失败重试用了多少；超预算不提交 |
| P1 | Redis 持久化和最小未完成任务对账 | 1–2 天 | 隔离环境清空队列后可恢复，已导入商品不会重复创建 |
| P1 公开前 | 固定 DNS 下载、公开部署配置、备份恢复 | 1.5–3 天 | 私网/映射地址与重绑定被拒绝，依赖端口受限，恢复数据演练通过 |
| P2 | 文档现状表、关键页面回归、路由拆包 | 1–2 天 | 新人能启动；关键保存/发布交互可重复检查；首屏包减小 |
| P2 | 20–30 个商品的 AI 标注样本集与指标 | 0.5–1 天起步，随后持续 | 类目修正率、文案修改率、图片可用率、耗时与费用有数据 |
不要把整张表变成开店前置条件。 对个人小批量自用，先完成 P0，并优先处理当前会碰到的收费风险；可用人工核对和少量任务运行控制其余风险。公开服务前则必须提升恢复、安全和预算控制标准。
7. 建议的两周工作分配
将可用于此项目的业余时间约 70% 用在商品与运营，30% 用在修阻塞和记录工程证据。这个比例是试验建议，不是市场统计或收益保证。
- 第一轮只选一个类目、3–5 个 SKU；供应链、包装、进货成本和物流可人工核实。图片够用即可，先避免为了每个商品生成完整套图。
- 逐条走现有链路，记录每个步骤耗时、失败原因和人工修改；发现阻塞只修当前阻塞。
- 导入后到 Ozon 后台完成库存、配送与实际售价，检查审核/可见性与图片。需要手工补的操作记录到一页清单，暂不开发新模块。
- 成为可售商品后，再观察曝光、点击、成交及可用平台经营数据；有订单时跟踪发货、退款和实际费用。没有订单时先核对需求、价格、交付和商品呈现，不能默认 ERP 自动化不足。
- 只有某个手工动作频繁发生，且明显占用时间或造成损失，再自动化它。没有复现需求就不开发自主 Agent、多平台、微服务或更多生图样式。
两周产出应是“一小批真实可售商品 + 真实耗时/失败/经营记录”，而不只是更多组件。不能承诺两周出单，成交取决于尚未验证的市场与供应链。
8. 如何变成 AI 全栈工程经历
你已经具备可讲述的技术范围：React/TypeScript、NestJS、PostgreSQL/RLS、BullMQ/Outbox、对象存储与签名交付、第三方平台集成、LLM 结构化生成和异步图片任务。下一步提高职业价值的方式是掌握设计与故障处理，并留下可核验成果。
可在简历中写：
独立开发 Ozon 商品采集与 AI 编辑工作台，采用 React/TypeScript、NestJS、PostgreSQL 和 BullMQ；实现工作空间隔离、SPU/SKU 编辑、结构化文案与类目建议、异步图片任务、定价快照及首次发布流程，并设计幂等、提交不确定时对账和图片交付校验。
如果大量代码由 AI 生成，面试时坦诚说明，并证明你能解释/维护关键设计。没有确认的性能、成功率、节省工时和收入数字不要写入简历。
建议整理 3 个脱敏案例：
- 真实集成故障：商品 imported 后缺图，如何分离商品/图片状态、检查跨境 CDN、确认真正恢复。
- 分布式与收费边界：模型已受理但本地未落库，为什么不能简单重试；如何做租期、代次、对账和人工处置。
- 业务正确性：SPU/SKU 继承、报价变更失效、快照发布、RLS 与跨租户约束，怎样用测试证明。
每个案例保留架构图、问题复现、关键决策、测试结果和最终限制。再用运营样本补充“人工上品平均耗时、AI 人工修改率、单商品费用、发布成功/缺图率”，这比再学一个 Agent 框架更能证明工程能力。
9. 未验证清单
本次未确认：真实进程有效环境变量、数据库所有迁移/角色/RLS 实际状态、店铺 VAT 与账户适用规则、当前佣金/物流费率、全部来源网页实时解析、真实 DeepSeek/生图服务质量和价格、真实 Ozon 新商品发布/审核/库存/可见性、当前 CDN 海外抓图、订单与净利润、部署与备份恢复、多用户压力与外部安全性。
结论来自静态证据、离线测试、额外模拟和明确标注的历史验收记录。静态代码存在、测试通过、历史单 SKU 验收，都不等于本次已真实线上跑通。