jacy/dukang
1
0
Fork 0
Code Issues Pull Requests Actions 13 Packages Projects Releases Wiki Activity
Files
main
dukang/AGENTS.md
T
jacy 233ed0af3b
CI / verify (pull_request) Has been cancelled
Details
v3.5.1 版本更新
2026-08-19 15:54:51 +08:00

8.0 KiB
Raw Permalink Blame History

杜康好客 · AGENTS.md

AI 编码入口。人类协作者仍读 agent.md；本文件供 Cursor / Codex / Copilot 等自动加载。

项目概览

杜康酒业 O2O 平台：购酒 → 发券 → 门店核销。Monorepo + 单体 NestJS（方案三：模块 OWNER）。

阶段 手册 说明
V3.0 唯一需求源 杜康好客-v3-PRD.md 产品需求与三波交付（只看这个）
现状对照 杜康好客-v3-现状对照.md 已完成 / 冲突 / 缺口审计
V3 实现验收 杜康好客-v3编码手册.md 核销规则、分工、闭环
V2 / preV1 历史参考（已压缩；V2 全文见 git 2026-08-06 前） 不再作为需求依据

禁止：臆造 PRD 未定义规则；依赖 doc/ 下过时文档；跨 OWNER 直写他人 Prisma 表。

启动命令

# 基础设施
cd deploy && docker compose up -d   # dukang-v1：MySQL :6016 Redis :6017

# 依赖与数据库
pnpm install
cp server/dukang-api/.env.example server/dukang-api/.env
pnpm db:generate && pnpm db:validate
cd server/dukang-api && npx prisma db push && pnpm prisma:seed

# 开发（分终端）
pnpm dev:api      # http://localhost:3010/api/v1
pnpm dev:user     # :5173
pnpm dev:shop     # :5174
pnpm dev:partner  # :5175
pnpm dev:admin    # preV1 HQ 替代（内部工具，非 V2 小程序）

# 验证
node scripts/smoke-v3.mjs
node scripts/smoke-prev1.mjs
pnpm lint && pnpm test

Mock 验证码：999888。测试账号见 README.md。

端口冲突：h5-partner 与 admin-web 同为 5175，勿同时 dev:partner + dev:admin。

文档优先级（冲突时）

  1. 杜康好客-v3-PRD.md — 唯一需求事实源
  2. 杜康好客-v3-现状对照.md — 实现进度审计
  3. 杜康好客-v3编码手册.md — 实现验收、核销、分工
  4. conventions.md — 协作与模块边界
  5. V2 手册 §四 §五 §六 — 仅作架构/DB/API 参考（与 V3 冲突时忽略）
  6. pages/{user,shop,partner,hq}/ — UI 参照

V2 / preV1 手册不再作为需求依据。

团队与 OWNER 边界（2 人）

负责人 Git 账号 职责
Jacy（管理员） jacy-dukang C 端、admin-web、后端主模块、packages、Prisma 迁移主 Review
刘景尧 刘景尧 合伙人 H5、门店 H5、store / redeem 模块（暂由 jacy-dukang 代管）

临时分工（2026-07）：刘景尧任务暂由 jacy-dukang 全权负责；逻辑 OWNER B+D 路径可改，Prisma 迁移由 jacy 主导。

逻辑模块边界仍按 A/B/C/D 划分（便于 Agent 隔离），当前人员合并如下：

逻辑 OWNER 负责人 可改路径 后端 Module
A + C + Lead + B + D jacy-dukang apps/*, packages/*, callbacks/, jobs/, common/, integrations/ 全部后端模块
B + D 刘景尧 — 恢复分工前由 jacy 代管

Prisma 迁移：jacy-dukang 主导 Review；涉及 store_* / 核销表时仍建议刘景尧知会（恢复分工后共同 Review）。

跨模块规则（R1–R8 摘要）

  • 只 inject 对方 Module exports 的 Service，禁止 prisma.xxx 写他人表
  • apps/* 禁止 import server/* 源码；只走 HTTP + packages/shared-types
  • 业务纯规则 → packages/domain；枚举/DTO → packages/shared-types
  • 微信/配送回调入口 仅 callbacks/；Mock 实现 仅 integrations/*

Cursor 规范

类型 路径 说明
Rules .cursor/rules/ 自动加载的编码规范
编码 Skill .cursor/skills/dukang-coding/ @dukang-coding
V3.0 需求 Skill .cursor/skills/dukang-v3/ @dukang-v3（PRD、Wave、REQ/ACC）
需求 Skill .cursor/skills/dukang-project/ @dukang-project
preV1 Skill .cursor/skills/dukang-prev1/ Mock / Feature Flag
任务卡 Skill .cursor/skills/dukang-task-card/ DLV-W* / P1-* / M*-*
发布 Skill .cursor/skills/dukang-release/ @杜康发布 / @dukang-release

子 Agent（按职责选用）

在 Cursor Agent 输入 / 选择：

子 Agent 负责人 适用场景
v3-delivery-lead jacy-dukang V3.0 三波交付统筹、DLV 拆分、跨 Owner 协调
v3-req-reviewer — V3.0 需求只读审查、REQ/ACC 缺口分析
owner-a-user-trade jacy-dukang C 端、订单、支付、权益、埋点
owner-c-catalog-ops jacy-dukang admin-web、开城商品、结算、运营
backend-lead jacy-dukang packages、callbacks、jobs、Prisma 横切
owner-b-partner-store 刘景尧 合伙人 H5、门店 CRUD/审核
owner-d-shop-redeem 刘景尧 门店 H5、核销
boundary-reviewer — PR 前只读审查跨模块违规

Skills（按需 @）

Skill 何时用
dukang-v3 V3.0 PRD、现状对照、Wave/REQ/ACC
dukang-coding 实现功能、修 Bug（通用编码流程）
dukang-project PRD/需求评审、原型对照、任务卡规划（不用于日常编码）
dukang-prev1 Mock 开关、preV1 裁剪、Feature Flag
dukang-task-card 领取任务卡 DLV-W*-* / P1-* / M*-* 并按 DoD 交付
dukang-release（杜康发布） dev_jacy→dev 合并 + deploy.sh 发版

快速指令

  • 现状审计：@dukang-v3 + 杜康好客-v3-现状对照.md
  • 实现 DLV 任务：@dukang-coding 实现 DLV-W1-M2
  • 波次规划：/v3-delivery-lead 拆分 Wave 2 任务
  • 需求缺口审查：/v3-req-reviewer 审查门店提现
  • PR 前审查：/boundary-reviewer
  • 原型参照：pages/{user,shop,partner}/（只读）

核心业务常量（不可偏离）

权益额 = benefit_amount ?? price
同城起购 2 瓶 / 跨城 6 瓶
核销：直接核销 0 < amount ≤ 全部 ACTIVE 权益总余额；带单据核销 0 < amount ≤ 该单据可用金额；Redis 码 3 分钟
C 端门店仅 status=OPEN
订单 Tab：待付款 | 已付款 | 已完成

iOS 微信 H5 JSSDK：登录/OAuth 后禁止仅 SPA 跳转再调扫码；见 packages/weixin-sdk/GOTCHAS.md、知识库「门店端 · 踩坑」。 微信小程序 open-type：chooseAvatar 等 Button 的祖先禁止 stopPropagation（会编成 catchtap）；见知识库「C 端 · 踩坑」、.cursor/rules/mini-user-weapp-opentype.mdc。 微信小程序页面标题：weapp 只用原生 navigationBarTitleText，不要再画一层与导航栏重复的 SubPageHeader title；见 .cursor/rules/mini-user-weapp-nav-title.mdc。

环境与发版

环境 分支 目录 端口 域名
local dev_jacy 本机 Docker 6016/6017 API :3010 —
staging 测试 dev /opt/dukang-staging 8190–8194 *-test.dukanghaoke.com
production 生产 main /opt/dukang 8090–8094 *.dukanghaoke.com
  • 日常发布 → deploy/deploy-staging.sh（dev）
  • 生产发布 → deploy/deploy-prod.sh（main，验收后）
  • Staging：正式微信 + 全 Mock；配置见 .env.staging.example
  • 详情：@dukang-release / .cursor/skills/dukang-release/SKILL.md

提交与 PR

  • Conventional Commits：feat(trade):、fix(redeem):；scope = 端或模块
  • 跨模块 PR → jacy-dukang + 刘景尧 共同 Review（若涉及双方模块）
  • 改 API/表 → 同步 v3-PRD + v3编码手册 + shared-types
  • 不提交 .env、dist/、node_modules/

完成定义（DoD）

  • 任务卡验收项全部满足
  • 未跨模块直写 Prisma 表
  • 枚举/DTO 在 shared-types；纯规则在 domain
  • pnpm lint 无新增错误；相关 domain 单测通过

嵌套指引

Reference in New Issue View Git Blame Copy Permalink