# Project Agent Guide ## 项目定位 这是一个面向个体户和手艺人的个人品牌小程序试点项目。当前第一个交付对象是朋友的真实品牌。 第一版的核心闭环是: ```text 品牌展示 -> 服务/作品了解 -> 客户预约或咨询 -> 管理员后台处理 -> 客户反馈 ``` 产品目标是帮助个人建立自己的品牌入口;后台和多品牌能力是实现手段,不要把项目优先级转向 SaaS、套餐、租户注册或平台流量。 ## 必读文档 开始开发或修改需求前,按以下顺序阅读: 0. `PROJECT_STATUS.md`:当前阶段、最近提交、下一步和未决问题;跨电脑恢复时优先阅读。 1. `docs/PRD.md`:产品范围、功能需求和验收标准。 2. `docs/01-prototype-spec.md`:页面、字段、状态和交互要求。 3. `docs/02-architecture-and-decisions.md`:技术选型和架构决策。 4. `docs/03-data-and-api-design.md`:数据模型、接口边界和上传流程。 5. `docs/04-implementation-plan.md`:里程碑、测试和发布清单。 6. `docs/05-pilot-case-food-stall.md`:当前首个试点的餐饮场景假设和待确认内容。 7. `docs/06-domain-extension-strategy.md`:个人品牌核心能力与行业扩展边界。 8. `docs/07-requirements-interview-decisions.md`:首轮访谈确认的订单与客户身份规则;冲突时优先于早期文档。 9. `docs/08-clickable-prototype.md`:低保真原型入口、演练路径和边界。 ## 已安装的成熟 Skills 项目当前复用以下外部 skill,不重复维护同类自定义规则: - `playwright-testing`:仅在编写或调试 Playwright E2E 测试时使用。重点遵循用户可见角色/标签定位、Page Object、失败截图和 trace。 - `codex-review-workflow`:在用户要求代码审查、自动质量验证,或功能完成需要正式 review 时使用。默认最多执行初审和一次复审,不把它用于普通探索任务。 这两个 skill 安装在用户级 `/Users/que01/.agents/skills/`,不属于项目源码。项目规则、产品边界和技术决策仍以本文件及 `docs/` 为准。 ## 当前已接受的技术决策 - Monorepo:`pnpm workspace + Turborepo` - 小程序:原生微信小程序 + TypeScript - 管理后台:React + TypeScript + Vite;本地使用 Vite proxy,生产使用 Nginx 反向代理 - API:NestJS + TypeScript - 数据库:PostgreSQL - ORM:Prisma - 图片:S3 兼容对象存储 - 后台登录:第一版账号密码,未来可绑定微信身份 - 发布:第一版人工使用微信开发者工具发布 ## 行业分叉前的架构不变量 - `Brand Core` 只负责个人身份、信任、业务展示、联系与咨询;行业字段和行业流程不得反向进入核心模型。 - 模板是声明式配置包,负责行业表达和默认配置;复杂排期、报价、库存、支付和行业状态机属于独立 capability。 - `Offering` 是服务、产品、套餐和订阅的统一业务身份;`Service` 仅保留为迁移兼容入口,新的核心流程不得建立新的 Service 关联。 - 动态表单必须声明用途、目标对象和提交动作,不能让客户端根据字段猜测是否创建预约或订单。 - 订单或预约状态由带版本的 workflow 定义,核心只提供状态、权限、审计和非法跳转保护。 - 小程序和 Admin 消费后端生成的 runtime workspace contract,不根据 `templateKey` 编写行业分支。 - 所有扩展 JSON 必须带 schema version,并在 DTO 或 capability validator 边界校验。 行业模板扩展前,必须先完成 `docs/adr/0003-industry-fork-readiness.md` 中的 Offering、品牌行业字段、表单动作、workflow 和 runtime workspace 五项收口。 ## 第一版范围 必须实现: - 小程序首页、品牌介绍、服务、作品集 - 客户无需注册提交预约/咨询 - 公开内容匿名浏览;下单使用微信无感身份,并提供“我的订单”。 - 普通套餐支持数量、自取/配送和预计总价;私厨由经营者人工报价。 - 后台支持订单未读、标签和内部备忘。 - 客户提交反馈,后台审核后公开 - 后台登录和权限校验 - 品牌、服务、作品内容管理 - 预约列表、状态和内部备注 - 图片上传、预览和基本错误处理 明确不实现: - 支付、退款、发票、财务对账 - 订单和支付状态 - 自动发布微信小程序 - 多商户注册、套餐和计费 - 多员工、多门店、复杂排班 - 会员、优惠券、营销自动化 - 自动消息通知 价格可以作为展示文本;可以预留金额字段,但不得在第一版创建支付入口或支付状态。未来支付应使用独立的 `Order`、`Payment`、`Refund` 模型,不能把支付状态塞进 `Booking`。 ## 开发规则 - 先确认原型和字段,再修改数据库;不要根据临时页面直接添加字段。 - 公开 API 与管理 API 分离。 - 前端隐藏管理入口不是权限控制,所有管理接口必须服务端鉴权。 - 联系方式、预约备注等敏感数据不得从公开接口返回。 - 内容删除优先使用停用、隐藏或软删除,保留预约和审核记录。 - 新增功能必须说明用户问题、优先级、数据影响和是否影响支付兼容性。 - 不要为了未来 SaaS 过早实现租户注册、计费和复杂权限。 - 不要将品牌文案、服务和作品写死在前端代码中。 - 共享类型和状态枚举放在 `packages/`,避免前后端重复定义。 - 任何涉及真实客户数据的调试输出都必须脱敏。 ## 推荐目录 ```text apps/miniapp # 微信小程序 apps/admin # Next.js 管理后台 apps/api # NestJS API packages/types packages/api-client packages/validation packages/config prisma/ docs/ ``` ## 工作方式 每完成一个里程碑,都要验证对应闭环,而不是只检查页面是否能打开: 1. 后台保存品牌资料,小程序能看到更新。 2. 后台创建服务,小程序能展示并支持预约。 3. 客户提交预约,后台能看到并更新状态。 4. 客户提交反馈,后台审核后小程序才能展示。 5. 未登录用户无法修改任何管理数据。 真实朋友使用前,先完成文档中的发布前检查和数据库备份方案。试点上线后再根据实际使用频率决定是否抽象多品牌和自动化能力。 ## Vibe Coding 最小规范 以下规则用于控制后续 AI 辅助开发的范围和上下文成本。 ### 开始任务前 1. 先阅读本文件和与任务直接相关的文档,不要一次加载全部代码。 2. 用一句话写清楚本次任务的结果和不包含的内容。 3. 先搜索现有实现,再决定新增文件还是修改现有文件。 4. 涉及数据库、公共类型或 API 契约时,先检查调用方。 ### 实现任务时 - 一次只处理一个可验证的小目标。 - 优先复用现有模式,不为单一需求新增抽象层。 - 每次修改保持在必要文件范围内,不顺手重构无关代码。 - 先实现业务闭环,再补样式、优化和扩展能力。 - 不实现 PRD 明确排除的功能,除非用户明确改变范围。 - 新增依赖前说明用途、替代方案和维护成本。 - 不把临时数据、品牌文案或密钥写死在代码中。 ### 完成任务前 1. 运行与改动匹配的最小验证:类型检查、单元测试、API 测试或手工流程。 2. 检查错误状态、空状态、权限边界和重复提交。 3. 检查是否引入敏感信息、无关文件或未记录的数据库变更。 4. 用简短记录说明改了什么、为什么改、如何验证、剩余风险。 ### 上下文和 token 控制 - 默认只读取完成当前任务所需的文件。 - 大文件先搜索相关符号和行号,再读取局部内容。 - 不重复输出已经确定的背景和完整代码。 - 计划超过三个步骤时,先写出短计划再执行。 - 遇到不确定的产品决策,优先依据 PRD;PRD 没有覆盖时记录假设,不要扩大实现范围。 ### 任务完成定义 任务只有同时满足以下条件才算完成: - 代码或文档已落盘。 - 相关验证已执行,或明确说明无法执行的原因。 - 变更符合第一版范围和数据/API 约束。 - 用户能根据结果继续下一步工作。 ## Trellis 风格交付流程 后续功能按固定阶段推进。阶段之间必须有可检查的产物,不能把“代码能运行”直接当作需求完成。 ### 1. 任务定义 - 用一句话写清用户问题、目标用户和期望结果; - 写明本次包含内容和明确不包含内容; - 确认是否属于个人品牌核心、配置包,或未来功能插件; - 检查 PRD、ADR、数据模型和当前状态,记录冲突和假设。 产物:任务说明、范围边界、验收场景。 ### 2. 方案边界 - 先定义领域对象、状态转换、权限边界和 API 契约; - 涉及模板时,先定义声明、版本、安装快照、升级和回滚语义; - 涉及数据时,先确定迁移兼容、旧数据默认值和恢复策略; - 明确失败路径、空状态、重复提交和用户可见文案。 产物:必要时新增 ADR;否则在任务记录中写出数据、接口和 UI 方案。 ### 3. 实现 - 先完成一个端到端的最小闭环; - Controller、Service、DTO、API Client 和页面按既有边界分层; - 任何新增 endpoint 必须同时新增授权测试和成功测试; - 任何 schema 变更必须同时更新 migration、seed、运行时代码和测试; - 不在实现过程中顺手扩大产品范围。 产物:可运行的代码、迁移和契约变更。 ### 4. 验证 - API:未授权、错误角色、成功、业务校验失败和数据隔离; - 数据:迁移可执行,旧数据可读,重复执行行为明确; - UI:loading、empty、error、retry、success、mutation failure 和重复点击; - 契约:API Client、DTO、响应 envelope 和页面调用一致; - 运行匹配的 typecheck、integration tests、production build、format check。 产物:测试结果和剩余风险记录。 ### 5. Code Review 收口 - 按用户场景重新走一遍,而不是只看 diff; - 检查是否存在“已实现但未测试”的操作; - 检查接口名称、产品文案和实际行为是否一致; - 检查回滚、删除、升级等破坏性语义是否明确; - 发现重复问题时,先更新本文件或 ADR,再开始下一项相关开发。 只有五个阶段都完成,且没有未解释的高风险项,才允许提交该里程碑。