yml2213andClaude Opus 4.5
4bcb4e6b57
客服人工履约有四个钱包，成本与渠道在后台配置好，客服确认履约时零输入。 口径（2026-10-24 确认）： - 四个钱包：南航积分 / 乐玩积分 / ROCK 积分 / 备用金现金。三平台积分互不通用， 每客服每平台一个积分账户；现金复用现有 fund_accounts / fund_entries。 - 积分换算率按平台不同：南航 1 积分 = 1 分，乐玩 1 积分 = 1 分， ROCK 1 积分 = 1 元（100 分）。真源是履约档案 config_json.rechargeUnitPriceFen。 - 积分是货币，幸运币是商品；消耗积分与成本金额按换算率一一对应。 - 配置主键是**内部 SKU**（快手 spec_json.skuNick / 拼多多 spec_json.outSkuSn）， 不是商品标题（标题是引流）。同名 SKU 算同一商品，跨渠道共用一份配置。 - 配置链路没有匹配引擎、没有打分：扫描 → 配置 → 重新匹配。 10 月口径下人工单 17,469 单 / 357 个内部 SKU，Top 50 覆盖 88% 单量。 更早的老单没配置意义，不纳入统计口径。 - 消耗积分填 0 = 成本不固定，客服在确认履约时手填实际成本； 渠道始终提前配好，客服不选。 迁移 110： - manual_sku_registry：扫描到的内部 SKU 登记表（统计 + 配置状态）。 - manual_fulfillment_configs：内部 SKU → 渠道 + 消耗积分 + 成本模式。 - platform_credit_accounts / platform_credit_entries：三平台积分钱包与流水。 - order_items.fulfillment_config_id：订单项挂配置，重新匹配时回填。 - 4 条 manual_* 履约档案（manual_dispatch 执行器 + config_json 区分平台）。 不复用 kuaishou_ct_assisted / kuaishou_feifei——那是已下线的历史自动发货通道。 性能：spec_json->>'skuNick' 无索引时扫描 2.4s / 回填 5.4s； 新增 idx_order_items_manual_internal_sku 表达式索引后回填降到 1.7s。 后端：manual-fulfillment-config-service.ts（扫描/清单/配置CRUD/重新匹配）， 成本中心挂 7 个接口。 前端：成本中心新增「人工 SKU 配置」Tab（扫描、清单、配置弹窗、重新匹配）。 校验：后端 765 项 / 0 失败（含 check:sql 迁移护栏），前端 143 项全通过； E2E 实测扫描 357 个 SKU、配置四平台换算正确、重新匹配回填 7,604 个订单项； 本地库迁移 110 执行后数据量与改造前一致。 Co-Authored-By: Claude Opus 4.5 (1M context) <noreply@anthropic.com>
order-site-backend
快手轻量后端：订单入库、履约任务编排、91 卡券 / kuaishou-cloud / kuaishou-feifei / 行业电子凭证对接、后台管理接口，以及数据库迁移。
快速启动
npm install
cp ../../.env.mac-docker.example ../../.env
npm run dev
推荐优先用仓库根目录 Docker 开发环境（含 PostgreSQL 与 Caddy）。
生产构建：
npm run build
npm run start
常用验证：
npm run typecheck
npm run build
npm test
配置
环境变量来自工作区根目录 .env：
- 默认值：
src/config/defaults.ts - 覆盖：根目录
.env
常用项：
| 变量 | 说明 |
|---|---|
PORT |
服务端口（Compose 中常由 BACKEND_PORT 映射） |
LOG_LEVEL |
debug / info / warn / error |
LOG_MAX_FILE_SIZE_MB |
单个应用日志文件大小上限，默认 20 MB，超出后轮转 |
LOG_MAX_FILES |
同一日期最多保留的日志文件数量，默认 5（含当前文件） |
LOG_RETENTION_DAYS |
日志日期保留天数，默认 30 |
DATABASE_URL |
PostgreSQL 连接串 |
ADMIN_SESSION_SECRET |
后台登录态签名密钥 |
ADMIN_DEFAULT_USERS_JSON |
默认后台用户 |
KAQUAN91_USER_ID / KAQUAN91_SECRET |
91 卡券凭据 |
接口
| 路径 | 说明 |
|---|---|
GET /health |
健康检查 |
GET /health/live |
存活 |
GET /health/ready |
就绪 |
/api/v1/open/91/* |
91 卡券开放接口 |
/api/v1/open/kuaishou-industry/* |
快手行业电子凭证 |
/api/v1/open/kuaishou-feifei/* |
发货平台 feifei 回调等 |
/api/v1/claim/* |
领取页接口 |
/api/v1/admin/* |
后台管理 |
/s/* |
短链跳转 |
目录
| 路径 | 职责 |
|---|---|
src/index.ts |
服务入口 |
src/app.ts |
Express 组装 |
src/routes |
API 路由 |
src/services/order |
订单与任务同步 |
src/services/fulfillment |
履约路由与执行器 |
src/services/platforms |
外部平台实现 |
src/services/admin |
后台读写与配置 |
src/repositories |
数据库访问 |
src/db/migrations |
SQL 迁移 |
数据库迁移
策略：001 基线 + 后续渐进增量。
| 文件 | 作用 |
|---|---|
src/db/migrations/001_init.sql |
空库完整基线结构 |
src/db/migrations/002_*.sql 起 |
增量变更 |
规则：
- 已应用的迁移文件禁止改内容。
- 结构变更只新增文件，不回写
001_init.sql。 - 启动时自动执行未应用迁移；记录在
schema_migrations。 - 文件名必须为
NNN_name.sql（三位序号）。
命令：
# 对齐状态
npm run db:migrate:status
# 手动 up
npm run db:migrate
# 创建下一份增量（生成 00N_xxx.sql 模板）
npm run db:migrate:create -- add_something
创建后编辑 SQL，与业务代码一并提交。Docker 开发环境示例：
docker compose -f ../../docker-compose.dev.yml exec -T backend npm run db:migrate:create -- add_something
docker compose -f ../../docker-compose.dev.yml exec -T backend npm run db:migrate
Docker 开发
开发 Compose 会挂载源码：
postgres提供开发库- 后端启动时安装依赖并
npm run dev - 改
src/或.env通常不必重建镜像
需要重建 backend 镜像的情况：
deploy/docker/backend*.Dockerfile变更- Node 版本或系统依赖变更
package.json/package-lock.json变更
运行产物
日志默认：
data/logs/app-YYYY-MM-DD.logdata/logs/integration-YYYY-MM-DD.log
按天切分并按大小轮转，默认单文件 20MB、单日最多 5 个分片、保留 30 天。成功的 GET/HEAD 请求以 DEBUG 记录，生产默认 LOG_LEVEL=info 不落盘；写请求和所有 4xx/5xx 仍保留 access log。成功的 /health* 探活默认不写 access log。
data/*.json 为本地运行配置，可能含敏感信息，默认不提交；请从 *.example.json 复制后填写。