Files

T

yeuimu f1e81872e7 fix(product-family): auto-merge SKUs after manual tag edits; fix session cookie path

问题2（SKU 无法自动合并，GBIU017 案例）四处叠加根因修复：
- 人工标签旧词「热转印」被封闭词表静默踢出合并矩阵 → CRAFT_TAG_ALIASES
  别名归一为「烫画」（矩阵归因与 CUSTOM 标签同路径生效）
- updateTags 缺任一定价维度组即整链掉出矩阵且人工接管后永不恢复 →
  缺啥补啥（按链接名派生补齐，人工勾选值不动，响应带 filledDimensionTags）
- autoGroup 只建新族从不并入已有族（产生 USIU005-2 类碎片）→ 并入已有
  autoManaged 同款族优先，无匹配才新建；同款仅人工锁定族则跳过并报告
- 名称回退分组键含物流备注，包邮/不包邮永不同组 → 新增族语义键
  familyNameKey（国家+品名+SKU），api/admin 两侧同构，合并默认勾选随之修复

附加：
- updateTags 后未归族链接自动并入匹配族（attachToMatchingFamily，响应带
  attachedFamilyId）
- 整理新增碎片族合并 consolidateFragments：纯碎片族并入带商品族并删除
  （保公开 goodId=族ID 稳定），带商品/覆盖价/人工锁定进人工复审报告
- admin：保存标签提示补齐明细，整理完成消息含并入/碎片合并/待人工数

问题1（后台频繁 Unauthorized 掉线）：
- refresh cookie path '/auth' 与代理前缀（/api、/v2-api）不匹配导致浏览器
  永远带不上 refresh cookie → 两 cookie path 统一为 '/'
- v2 构建基址带尾斜杠 + 手工拼接产生 /v2-api//auth/refresh 双斜杠 404 →
  request.ts 规范拼接

测试：api jest 187/187、admin vitest 22/22、双侧 tsc 0 错误；
public.service 夹具改为自包含（不依赖共享库既有数据）。

2026-09-02 18:39:35 +08:00

6.0 KiB

Raw Blame History

AGENT.md - AI Agent 开发规范

开发流程

1. 梳理需求

使用 brainstorming 进行头脑风暴, 文档存放与命名规则如下:

需求类型	计划目录	命名规则	示例
新功能	`plans/feature/`	`xxx-xxx-feature.md`	`smart-view-feature.md`
修 Bug	`plans/fix/`	`xxx-xxx-fix.md`	`token-refresh-fix.md`
重构	`plans/refactor/`	`xxx-xxx-refactor.md`	`api-split-refactor.md`

使用 writing-plans 技能制定实施计划

开发新功能时必须评估权限需求：每个新功能/新操作都需要考虑是否需要纳入权限控制。具体评估方式见下方「权限系统」章节。

可参考的开发文档位于 docs/dev/*

2. 建立开发分支

确定好需求之后，就使用 enterprise-git-spec 技能来建立分支。

3. 按照需求开发

按照当前功能的计划文档的任务项及其任务细节来逐步实现功能, 全程严格地遵循技能 test-driven-development 进行 TDD 开发流程, 并遵循 executing-plans 技能来执行开发计划。

重要原则：所有测试必须通过

开发过程中，必须确保所有测试用例都通过，包括新功能的测试和现有功能的测试
如果发现现有测试失败，必须立即修复，确保新功能不会破坏旧功能
只有在所有测试都通过的情况下，才能认为开发完成

所有任务完成后请遵循 verification-before-completion 技能完成验证

4. 合并到开发分支

所有测试通过后，使用 enterprise-git-spec 技能提交分支，然后合并回 develop 分支。

5. 沉淀开发经验

在实现功能过程中，将适用于任何项目的编码好想法、好思想、注意点等有助于项目推进的内容，及时追加到 AGENT.md 中。这些经验是跨功能、跨项目的通用知识，帮助后续开发少走弯路。

6. 更新项目结构文档

每次功能开发完成后，更新 docs/references/structs.md 文件。该文件记录整个项目的目录结构和每个模块的简要功能描述，便于每次迭代功能时快速理解整个项目全貌。

7. 更新使用文档

使用文档分为：

README.md - 面向人类使用者，帮助其快速上手项目。仅在新功能开发完成后更新。内容保持简洁，聚焦于让用户快速跑通基础流程。
docs/references/* - 面向人类使用者，提供项目的全面使用指南，支持深度探索模块与命令行细节。每次新功能开发完成或已有功能调整后必须更新。示例要丰富，帮助使用者理解各项功能的具体用法。
skills/[项目名]/SKILL.md - 面向 LLM / AI Agent，指导大模型如何使用本项目。

快速开始文档每次新功能开发完成后才更新，具体更新 README.md 文件。确保文档包含新增功能的使用示例、命令说明和注意事项，帮助用户快速上手。

详细使用文档位于 docs/references/*，目录文件为 docs/references/index.md，请按照功能划分参考文档，并填充详细的使用说明，帮助用户深度探索模块/命令行的使用。每次新功能或旧功能调整了请更新最新的使用方法，例子应该丰富一些，便于使用者理解功能使用。

AGENT使用技能文档位于 skills/[项目名]/*，入口文件为 skills/[项目名]/SKILL.md，更新时机和要求与详细使用文档一致。

开发规范

代码优化

遵循 improve-codebase-architecture

类型规范

参考技能 typescript-advanced-types

测试规范

参考技能 javascript-testing-patterns

测试

每个任务目录应有对应的测试文件 test/sync/tasks/<task-name>/handler.test.ts。

数据库设计

PostgreSQL 最佳设计实践: postgresql-table-design 技能 PostgreSQL 最佳性能调优实践: supabase-postgres-best-practices 技能 Prisma Postgres 最佳实践: prisma-postgres 技能

后端规范

参考 nestjs-best-practices 技能

你可以自己增加规范

经验沉淀（跨项目通用）

数据库漂移处理：连共享开发库时先跑 prisma migrate status；若报"列已存在"类错误，说明有人用 db push 带外改过库，用 prisma migrate resolve --applied <name> 把已存在的迁移标记为已应用，再 migrate deploy 应用真正缺的部分。切勿盲目 reset 共享库。
连真实库的集成测试隔离：jest 并行套件共用一个数据库时，(a) 夹具的天然键（sdsCategoryId、名称等）必须带运行时间戳唯一化，禁止跨运行共享字面量；(b) 全量型操作（如 auto-group 扫全库）会顺带扫到其他并行套件的夹具，其写入路径必须对"成员中途消失"宽容（跳过而非抛错），否则会随机挂测试。
跑全量 jest 前先停 dev server：nest start --watch 等常驻进程与测试共用数据库时，其重编译窗口/后台钩子会与测试写入竞争，造成"单跑绿、全量偶发红"的假阳性；验证基线前先停掉所有 watch 进程再跑。
中文断言勿手写字面量排序：JS Array.sort() 对中文按 UTF-16 码位排（如烫 U+70EB < 直 U+76F4），手写期望序列容易按拼音/习惯顺序写反；比较选项集合时用 expect.arrayContaining + 长度，或对两侧统一 .sort() 后再比较。
测试夹具必须自包含：断言库内"存在某类数据"的用例（如标签组过滤）在全新/一次性数据库上必挂；夹具自己种下断言所依赖的数据，不依赖共享库的既有状态。
严禁直接热修运行容器内的代码：本次线上 v2 镜像内被塞过未提交的词表改动（热转印），仓库重建镜像即复发且难排查；所有修复必须落在仓库并重建部署。排查"线上行为与代码不符"时先 md5sum 比对容器内源文件与仓库。

6.0 KiB Raw Blame History Unescape Escape