Files
persionalBrand/agent.md
T

213 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
- 管理后台: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 约束。
- 用户能根据结果继续下一步工作。
## 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,再开始下一项相关开发。
只有五个阶段都完成,且没有未解释的高风险项,才允许提交该里程碑。