docs: define initial product requirements

agent.md

@@ -0,0 +1,158 @@
+# Project Agent Guide
+
+## 项目定位
+
+这是一个面向个体户和手艺人的个人品牌小程序试点项目。当前第一个交付对象是朋友的真实品牌。
+
+第一版的核心闭环是：
+
+```text
+品牌展示 -> 服务/作品了解 -> 客户预约或咨询 -> 管理员后台处理 -> 客户反馈
+```
+
+产品目标是帮助个人建立自己的品牌入口；后台和多品牌能力是实现手段，不要把项目优先级转向 SaaS、套餐、租户注册或平台流量。
+
+## 必读文档
+
+开始开发或修改需求前，按以下顺序阅读：
+
+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`：首轮访谈确认的订单与客户身份规则；冲突时优先于早期文档。
+
+## 已安装的成熟 Skills
+
+项目当前复用以下外部 skill，不重复维护同类自定义规则：
+
+- `playwright-testing`：仅在编写或调试 Playwright E2E 测试时使用。重点遵循用户可见角色/标签定位、Page Object、失败截图和 trace。
+- `codex-review-workflow`：在用户要求代码审查、自动质量验证，或功能完成需要正式 review 时使用。默认最多执行初审和一次复审，不把它用于普通探索任务。
+
+这两个 skill 安装在用户级 `/Users/que01/.agents/skills/`，不属于项目源码。项目规则、产品边界和技术决策仍以本文件及 `docs/` 为准。
+
+## 当前已接受的技术决策
+
+- Monorepo：`pnpm workspace + Turborepo`
+- 小程序：原生微信小程序 + TypeScript
+- 管理后台：Next.js + TypeScript
+- API：NestJS + TypeScript
+- 数据库：PostgreSQL
+- ORM：Prisma
+- 图片：S3 兼容对象存储
+- 后台登录：第一版账号密码，未来可绑定微信身份
+- 发布：第一版人工使用微信开发者工具发布
+
+## 第一版范围
+
+必须实现：
+
+- 小程序首页、品牌介绍、服务、作品集
+- 客户无需注册提交预约/咨询
+- 公开内容匿名浏览；下单使用微信无感身份，并提供“我的订单”。
+- 普通套餐支持数量、自取/配送和预计总价；私厨由经营者人工报价。
+- 后台支持订单未读、标签和内部备忘。
+- 客户提交反馈，后台审核后公开
+- 后台登录和权限校验
+- 品牌、服务、作品内容管理
+- 预约列表、状态和内部备注
+- 图片上传、预览和基本错误处理
+
+明确不实现：
+
+- 支付、退款、发票、财务对账
+- 订单和支付状态
+- 自动发布微信小程序
+- 多商户注册、套餐和计费
+- 多员工、多门店、复杂排班
+- 会员、优惠券、营销自动化
+- 自动消息通知
+
+价格可以作为展示文本；可以预留金额字段，但不得在第一版创建支付入口或支付状态。未来支付应使用独立的 `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 约束。
+- 用户能根据结果继续下一步工作。