dukang/conventions.md

杜康好客 · 协同与开发规范

V3 交付验收：杜康好客-v3编码手册.md
完整蓝图：杜康好客-V2编码手册.md（与 V3 冲突时 V3 优先）
preV1 历史：杜康好客-preV1编码手册.md

---

1. 代码所有权

见 .github/CODEOWNERS。2 人团队（Git 账号）：

Git 账号	角色	主责
jacy-dukang	管理员 + 主责开发	C 端、admin-web、后端主模块、横切
刘景尧	刘景尧	合伙人 H5、门店 H5、store/redeem 模块

端与后端模块边界：

目录	负责人	说明
apps/h5-user	jacy-dukang	C 端 H5（V2 → mini-user）
apps/admin-web	jacy-dukang	preV1 总部替代
apps/h5-partner	刘景尧	合伙人 H5
apps/h5-shop	刘景尧	门店 H5
server/.../modules/{iam,trade,benefit,analytics}	jacy-dukang	交易与权益域
server/.../modules/{catalog,settlement,ops}	jacy-dukang	开城与结算域
server/.../modules/store	刘景尧	门店域
server/.../modules/redeem	刘景尧	核销域
server/.../callbacks, jobs, common, integrations	jacy-dukang	回调与任务
packages/*	jacy-dukang 主责；破坏性改动通知刘景尧	公共契约
server/dukang-api/prisma	jacy-dukang + 刘景尧（涉及 store/redeem 表时）	迁移 Review

---

2. 模块边界（机器 + 人工）

• 任一 apps/* 禁止 import 另一个 app 或 server/* 源码。
• 后端 Module 禁止 跨模块直写 Prisma 表，只 inject 对方 exports 的 Service（见编码手册 §四 §2.5）。
• 共享逻辑：packages/shared-types（DTO/枚举）、packages/domain（纯函数规则）。
• 计划引入 eslint-plugin-boundaries，在 pnpm lint / CI 阶段强制。

---

3. 接口契约

• 单一事实源：packages/shared-types + 杜康好客-V2编码手册.md §六。
• 加法优先：新字段 optional；删除/改名先 deprecated。
• 改了 API 必须同步更新手册 §六 与 shared-types。
• 破坏性变更走 URI 版本 /v1 → /v2。

---

4. 数据库契约（v3.1）

• 表结构事实源：编码手册 §五（28 表，user_/common_/log_ 等前缀）。
• Prisma schema 与手册保持一致；初始化 SQL 见 server/dukang-api/prisma/init_v3.sql。
• 关键约定：
  • C 端 user_user.phone 唯一；B 端 store_account / partner_account / hq_account 三表分离
  • 无 payments / user_order_item / redeem_tokens 表
  • 埋点 → log_user_analytics；业务事件 → common_event；工单 → common_ticket

---

5. 分支与提交

• feature 分支 + 小步 PR；跨模块改动需相关双 Owner Review。
• Conventional Commits，scope 用端或模块名：feat(user)、fix(trade)、chore(shared-types)。

---

6. 本地环境

• Docker Compose 起 MySQL + Redis + server（M0 交付 deploy/docker-compose.yml）。
• 敏感配置走 .env，不入库。
• DATABASE_URL 配置后：npx prisma migrate dev 或执行 init_v3.sql。

---

7. 原型参照

• UI 以 pages/{user,shop,partner,hq}/ 为准；与 PRD 映射见编码手册 §二、§三。
• C 端订单列表必须为 5 Tab（含待发货）；V1 无会员等级标签。