服装电商达人分销场景的全栈业务系统。 单人 + Claude Code，30 天从 0 到生产环境。 本仓库为个人作品集展示，代码已脱敏。
「达人分销」是服装电商常见的销售模式：商家把样衣寄给达人（主播 / KOL），达人通过短视频或直播带货，活动结束后样衣需要寄回。
这个流程涉及几个关键约束：
- 多商务多达人 — 商务团队几人到几十人，每人对接几十个达人，同时在外的样衣可达几百件
- 库存联动 — 寄样意味着出库，收样意味着入库，必须和 ERP 实时同步
- 超期催收 — 样衣寄出后达人长期不回是常见的隐形损失
- 成本敏感 — 商务不能看到成本价（避免飞单），但管理层需要核算利润
传统做法是 Excel + 微信群，对账困难、易出错、无法追踪。本系统将整个流程线上化，对接聚水潭 ERP，覆盖从扫码寄样到 FIFO 收样、催收预警、成本核算的完整闭环。
| 维度 | 数据 |
|---|---|
| 开发周期 | 2026-03-09 ~ 2026-04-07（30 天） |
| 总 commit | 128 |
| 代码量 | ~11,800 行 TypeScript（净增 17,668 行 / 总改动 101,742 行） |
| 删除率 | 70%（高频重构而非堆代码） |
| 数据库表 | 11 张 |
| API 端点 | 34 个 |
| 业务页面 | 10 个 |
| Service 模块 | 6 个 |
| 测试用例 | 19 个（vitest，100% 通过） |
| 正式版本 | 7 个（v0.1.0 ~ v0.3.2） |
| 变更文档 | 6 篇（架构 1 / 故障 4 / 运维 1） |
| 周 | Commits | 阶段 |
|---|---|---|
| W11 | 2 | 项目启动 |
| W12 | 18 | 骨架搭建 |
| W13 | 35 | 核心业务 + 聚水潭对接 |
| W14 | 52 | v0.1 发布 + 高峰修复 |
| W15 | 21 | 收尾迭代 |
7 个版本均有 git tag 标注，从初版上线到稳定版本耗时 8 天。
最小可用版本。完整覆盖：
- 寄样单 / 收样单 CRUD + 扫码登记
- 达人 CRM（创建、编辑、转让、列表搜索）
- 用户认证（admin / business 双角色）
- 数据隔离 + 三层成本价过滤
- 仪表盘、Excel 导出、催收预警
- 聚水潭库存查询 + SKU 商品同步
迭代历程：docs/changes/ops/001_v0.1.0-release.md
触发自 Issue #1：管理员修改用户名后，已登录用户的右上角依然显示旧值。
调研后发现是架构层面的问题：原 getSession() 仅从 cookie 解码用户信息，不查数据库。改为 cookie 验证签名后再查 DB 取最新 user 信息。
完整决策记录：docs/changes/arch/001_session-db-sync.md
附带收益：
- 管理员修改 role 后权限实时生效
- 禁用用户后 session 立即失效
- 无需强制用户重新登录
一次性修复 6 个 issue：
- #7 扫码登记权限开关（users 表新增
canScan字段） - #8 寄样 / 收样列表添加商务筛选
- #9 达人 / 订单删除功能（含级联删除）
- #10 在外样衣弹窗点击跳转
- #11 批量分配达人（管理员批量转让）
- #12 移动端底部导航栏
完整清单：docs/changes/fix/003_issues-7-12-batch-fix.md
主仓编号从 1 切到自定义 2 仓（编号 7）。同步修改库存查询逻辑：聚水潭 /open/inventory/query 没有 warehouse 请求参数，需要在响应中按 wh_id 过滤。
- 达人 S/A/B/C 评级，列表按 tier + 未收回数量排序
- 工作台精简（移除冗余卡片）
- 「样衣追踪」与「寄样列表」合并
- 新增
scripts/deploy.sh+/api/build-id端点，实现 push → CDN → 验证闭环 - Issue 模板调整
- 移除标签系统（实际使用率低，简化为 tier 评级）
- 批量设置等级
- 列表分页
修复商务账号在批量分配场景下无法勾选的权限判断 bug。
- 创建寄样单（连续扫码 + 数量校验 + 库存上限）
- 收样单 FIFO 自动关联（基于"达人 + SKU"窗口函数累积分配）
- 跟进记录 + 异常标记
- 超期预警（5 天关心、20 天催收升级）
- 多维度 CSV 导出（寄样、收样、在外样衣、催收列表，含 BOM 头兼容 Excel）
最复杂的逻辑集中在 services/sample.service.ts，1128 行，包含 FIFO 分配 CTE、各类导出函数、统计聚合查询。
- 达人档案（姓名、电话、地址、tier）
- S/A/B/C 评级 + 自定义排序权重
- 单个 / 批量转让（管理员操作）
- 删除时级联清理订单、明细、跟进、同步日志
- 按"未收回数量"智能排序
实现：services/talent.service.ts（287 行）
- 库存实时查询 + 寄样数量上限校验
- SKU 商品信息同步（缓存 + 三态机：完整 / 占位 / 重试）
- 自动调拨同步（"待确认"模式，绕过实时库存校验）
- 同步日志 + 失败重试机制
- 自定义 MD5 签名（实测：只前面拼 secret，文档未明示）
实现：services/jst.service.ts（471 行）+ services/jst-sync.service.ts（231 行）
- admin / business 双角色，数据按 userId 隔离
- 三层成本价过滤（API 层 + 前端层 + 导出层）
- 关键操作审计日志（创建、转让、删除）
- 可禁用账号 + 可单独禁用扫码权限
- 实时统计卡片（在外数量、超期催收、商务排行）
- 多个维度 CSV 导出
- 移动端 + 桌面端两套视图
users (账号: admin / business) │ ├──→ talents (达人) │ │ │ ├──→ orders (寄样 / 收样单) │ │ │ │ │ ├──→ order_items (SKU 明细) │ │ ├──→ order_followups (跟进记录) │ │ └──→ jst_sync_logs (聚水潭同步) │ │ │ └──→ talent_tag_assignments │ └──→ talent_tags (标签，v0.3.1 后弃用) │ └──→ audit_logs (操作审计) sku_products (SKU 缓存，来自聚水潭，独立表) app_settings (全局 KV 配置)
11 张表，3 个核心实体（User / Talent / Order），完整的多对多关系和级联删除处理。
完整 schema：lib/db/schema.ts
所有非平凡变更都有对应的变更文档。三类：
| 类型 | 数量 | 模板 |
|---|---|---|
| arch/ 架构决策 | 1 | 背景 + 方案对比表 + 决策 + 额外收益 |
| fix/ 故障修复 | 4 | 事件概述 + 修改清单 + 数据库迁移 + 验证结果 |
| ops/ 生产操作 | 1 | 发布清单 + 仓库治理 + 已知坑 |
文档不是事后补的，是和代码同期写的。新增模块前先写决策文档，避免实施过半发现方案有问题。
完整索引：docs/README.md
- 框架：Vitest
- 用例数：19
- 覆盖：FIFO 分配、SKU 搜索、扫码校验、关键查询
- 测试文件：
__tests__/sample.service.test.ts
bun run test # 一次性跑
bun run test:watch # 监听模式
每次 commit 前必跑 lint + tsc + test 三件套：
bun run lint && bunx tsc --noEmit && bun run test
scripts/deploy.sh 实现完整闭环：
git push ↓ 触发 EdgeOne webhook ↓ 轮询 /api/build-id 端点 ↓ 检测到新版本 commit hash ↓ 报告部署完成 + 站点 URL
最长等待 5 分钟，10 秒检查一次。配合 PostToolUse hook + 浏览器自动化，可以做到提交后无需人工介入即可验证生产环境。
Drizzle Kit 工具链：
bun run db:generate # 生成迁移 SQL
bun run db:migrate # 应用迁移
bun run db:push # 直接同步 schema（开发环境）
bun run db:studio # 可视化数据库
每次 schema 变更都附带迁移记录。
针对线上 issue 的批量验证脚本：
scripts/verify-all-issues.ts— Issue 全量验证scripts/verify-fixes.ts— 修复验证scripts/test-sku-validate.ts— SKU 校验测试scripts/perf-check.sh— 性能检查（dangerouslySetInnerHTML / next/image / React.memo 等模式扫描）scripts/seed.ts— 测试数据播种
src/ ├── app/ │ ├── (auth)/ │ │ └── login/ # 登录页 │ ├── (main)/ # 主应用路由组 │ │ ├── dashboard/ # 工作台 │ │ ├── samples/ # 样衣追踪 + 新建 + 详情 │ │ ├── receives/ # 收样列表 │ │ └── talents/ # 达人管理 + 详情 │ ├── admin/ │ │ └── users/ # 账号管理（admin only） │ └── api/ # 34 个 API 端点 │ ├── auth/ │ ├── admin/ │ ├── samples/ │ ├── receives/ │ ├── talents/ │ ├── products/ │ ├── dashboard/ │ └── build-id/ │ ├── services/ # 业务服务层（6 个，2153 行） │ ├── sample.service.ts # 1128 行 — 最复杂的业务逻辑 │ ├── jst.service.ts # 471 行 — 聚水潭 API 封装 │ ├── talent.service.ts # 287 行 — 达人管理 │ ├── jst-sync.service.ts # 231 行 — 同步逻辑 │ ├── audit.service.ts # 19 行 — 审计日志 │ └── config.service.ts # 17 行 — 全局配置 │ ├── lib/ │ ├── db/ │ │ ├── schema.ts # Drizzle schema (11 表) │ │ └── index.ts # DB 连接 │ ├── auth/ │ │ └── session.ts # HMAC-SHA256 cookie + DB 同步 │ └── utils.ts │ ├── components/ │ ├── ui/ # 21 个 shadcn/ui 基础组件 │ ├── layout/ │ │ ├── Sidebar.tsx │ │ ├── Header.tsx │ │ └── MobileNav.tsx # v0.2.1 新增 │ └── sample/ # 寄样相关业务组件 │ ├── __tests__/ │ └── sample.service.test.ts # 19 个用例 │ ├── scripts/ # 部署 / 验证 / 迁移脚本 │ ├── deploy.sh │ ├── perf-check.sh │ ├── verify-all-issues.ts │ ├── verify-fixes.ts │ ├── test-sku-validate.ts │ ├── seed.ts │ └── migrate-can-scan.sql │ └── docs/ ├── README.md # 文档索引 └── changes/ ├── arch/ # 架构决策 ├── fix/ # 故障修复 └── ops/ # 生产操作
| 决策 | 选择 | 原因 |
|---|---|---|
| ORM | Drizzle | 更接近 SQL，复杂查询（CTE、窗口函数）支持更好 |
| 数据库 | Neon Serverless PostgreSQL | 0 运维 + 按量付费 + 兼容 Edge Runtime |
| 认证 | 自定义 HMAC-SHA256 Cookie | 业务简单，避免引入 NextAuth 的复杂度 |
| UI 库 | Tailwind v4 + shadcn/ui | 复制式组件库，完全可控 |
| 状态管理 | SWR | 简单缓存 + 自动重新验证，足够 |
| 表单校验 | Zod | 类型安全 + 服务端 / 客户端共享 schema |
| CDN | EdgeOne | 国内访问速度 + 价格 |
| ERP 同步策略 | 调拨「待确认」模式 | 绕过聚水潭实时库存校验，符合"商务先发起、仓库后确认"的真实节奏 |
| Session 一致性 | DB 实时查询 | Cookie-only 方案在角色 / 用户名变更时无法及时同步 |
本仓库仅用于个人作品集展示，不提供商业授权。 原项目仍在生产环境运行，代码已脱敏。
