jacy/dukang

Fork 0

Files

T

jacy 743d242d52 v3计划内容上传

2026-07-04 20:36:26 +08:00

5.7 KiB

Raw Blame History

杜康好客 · AGENTS.md

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

项目概览

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

阶段	手册	说明
当前 preV1	`杜康好客-preV1编码手册.md`	三端 H5 + Mock 联调，同库同 API
目标 V2	`杜康好客-V2编码手册.md`	四端小程序 + 真实第三方（唯一事实源）

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

启动命令

# 基础设施
cd deploy && docker compose up -d

# 依赖与数据库
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:3000/api/v1
pnpm dev:user     # :5173
pnpm dev:shop     # :5174
pnpm dev:partner  # :5175
pnpm dev:admin    # preV1 HQ 替代（内部工具，非 V2 小程序）

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

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

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

文档优先级（冲突时）

杜康好客-V2编码手册.md §二 — 业务规则
杜康好客-preV1编码手册.md — preV1 裁剪（Mock / Flag）
conventions.md — 协作与模块边界
V2 手册 §四 §五 §六 — 架构 / DB / API
pages/{user,shop,partner}/ + pages/ROUTE_MAP.md — UI 参照

团队与 OWNER 边界（2 人）

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

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

逻辑 OWNER	负责人	可改路径	后端 Module
A + C + Lead	jacy-dukang	`apps/h5-user/`, `apps/admin-web/`, `packages/*`, `callbacks/`, `jobs/`, `common/`, `integrations/`	`iam`, `trade`, `benefit`, `analytics`, `catalog`, `settlement`, `ops`
B + D	刘景尧	`apps/h5-partner/`, `apps/h5-shop/`	`store`, `redeem`

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
需求 Skill	`.cursor/skills/dukang-project/`	@dukang-project
preV1 Skill	`.cursor/skills/dukang-prev1/`	Mock / Feature Flag
任务卡 Skill	`.cursor/skills/dukang-task-card/`	P1-* / M-

子 Agent（按职责选用）

在 Cursor Agent 输入 / 选择：

子 Agent	负责人	适用场景
`owner-a-user-trade`	jacy-dukang	C 端 H5、订单、支付、权益、埋点
`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-coding`	实现功能、修 Bug（通用编码流程）
`dukang-project`	PRD/需求评审、原型对照、任务卡规划（不用于日常编码）
`dukang-prev1`	Mock 开关、preV1 裁剪、Feature Flag
`dukang-task-card`	领取任务卡 `P1-` / `M-*` 并按 DoD 交付

快速指令

实现任务卡：@dukang-coding 实现 P1-M2-002
需求评审：@dukang-project 对照 pages/partner/ 评审 PRD
PR 前审查：/boundary-reviewer
原型参照：pages/{user,shop,partner}/（只读）

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

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

提交与 PR

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

完成定义（DoD）

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

嵌套指引

后端细节：server/dukang-api/AGENTS.md
前端四 App：apps/AGENTS.md

5.7 KiB Raw Blame History Unescape Escape