From 7dfa603ba8a2c26dd34590dce052d02bb96723a6 Mon Sep 17 00:00:00 2001
From: que01 <que01@foxmail.com>
Date: Fri, 18 Sep 2026 17:48:18 +0800
Subject: [PATCH] docs: add persistent project status handoff

---
 PROJECT_STATUS.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++
 agent.md          |  1 +
 2 files changed, 90 insertions(+)
 create mode 100644 PROJECT_STATUS.md

diff --git a/PROJECT_STATUS.md b/PROJECT_STATUS.md
new file mode 100644
index 0000000..808f9ca
--- /dev/null
+++ b/PROJECT_STATUS.md
@@ -0,0 +1,89 @@
+# Project Status
+
+最后更新：2026-09-18
+
+## 当前目标
+
+先为餐饮摊主朋友交付一个真正能带来订单的个人品牌小程序，再根据真实使用把通用能力产品化。产品方的收益、运营和平台化目标不能牺牲朋友的实际使用效果。
+
+## 当前阶段
+
+后端基础与工程环境已建立，正在把 API 做到可以交给小程序和管理后台接入的程度。小程序和后台页面尚未接入真实 API。
+
+## 已完成
+
+- 产品 PRD、原型规格、架构决策、数据/API 设计和实施计划。
+- 餐饮试点画像与首轮需求访谈决策。
+- 可点击低保真原型：`prototype/index.html`。
+- Git 仓库、`main` 分支和远程仓库。
+- pnpm workspace + Turborepo Monorepo。
+- TypeScript 严格配置、ESLint、Prettier、EditorConfig、环境变量模板。
+- NestJS + Fastify API 骨架。
+- Prisma PostgreSQL schema：品牌、服务、客户身份、订单、订单明细、标签、管理员。
+- 微信官方 `jscode2session` 登录交换边界。
+- 客户登录 token、客户订单提交/查询/取消。
+- 普通套餐价格快照和私厨需求人工报价模型。
+- 管理员账号密码登录和角色 token。
+- 管理员订单列表、状态、未读、标签和内部备忘能力。
+- DTO 校验、全局异常响应、请求 ID和订单状态流转规则。
+- Docker PostgreSQL Compose、seed 和 Prisma 脚本说明。
+- 已执行多轮 Codex 代码审查并修复关键认证和权限问题。
+
+## 最近提交
+
+```text
+f2687c5 chore: prepare portable postgres development environment
+0e8b8e1 feat: add api http conventions and booking state rules
+0d4caab feat: add admin order tags and read state
+bb5ccb1 feat: add admin authentication
+b89853b fix: harden api authentication and validation
+```
+
+远程：`https://git.app.que01.top/que01/persionalBrand.git`
+
+## 下一步优先级
+
+1. 在有 Docker/PostgreSQL 的机器执行 Prisma migration 和 seed，确认真实数据库可运行。
+2. 修正并补齐 API 集成测试：客户隔离、订单提交、取消、状态机、管理员权限、标签归属。
+3. 补管理员订单详情、筛选和未读数量接口。
+4. 补 OpenAPI/Swagger 契约和统一响应示例。
+5. 创建类型化 `api-client`，再接入管理后台和小程序。
+6. 先接管理后台订单处理，再接小程序品牌展示和下单。
+
+## 未决问题
+
+- 普通套餐采用固定菜单、每日菜单，还是固定套餐加每日可用状态。
+- 朋友最终品牌名称、图片、联系方式、营业时间和配送范围。
+- 微信小程序主体、AppID、服务类目和订阅消息模板是否可用。
+- 生产部署使用哪家 PostgreSQL、对象存储和 API 托管服务。
+- 当前 token 是开发阶段的签名 Bearer token；生产前应替换为带撤销能力的正式 session/Cookie 方案。
+
+## 当前明确不做
+
+- 支付、退款、发票、财务对账。
+- 复杂库存、自动配送判断和每日菜单编排。
+- 多商户注册、套餐计费、会员和营销系统。
+- 自动发布微信小程序。
+
+## 跨电脑恢复
+
+```bash
+git clone https://git.app.que01.top/que01/persionalBrand.git
+cd persionalBrand
+cat PROJECT_STATUS.md
+cat agent.md
+cp .env.example .env
+```
+
+有 Docker 的机器再执行：
+
+```bash
+docker compose up -d postgres
+pnpm install
+pnpm db:migrate
+pnpm db:seed
+```
+
+## 更新规则
+
+每完成一个可验证的开发任务，更新“当前阶段”“已完成”“最近提交”和“下一步优先级”。只记录已经发生或已经确认的事实；未确认内容放入“未决问题”。
diff --git a/agent.md b/agent.md
index e2743bb..424f81b 100644
--- a/agent.md
+++ b/agent.md
@@ -16,6 +16,7 @@
 
 开始开发或修改需求前，按以下顺序阅读：
 
+0. `PROJECT_STATUS.md`：当前阶段、最近提交、下一步和未决问题；跨电脑恢复时优先阅读。
 1. `docs/PRD.md`：产品范围、功能需求和验收标准。
 2. `docs/01-prototype-spec.md`：页面、字段、状态和交互要求。
 3. `docs/02-architecture-and-decisions.md`：技术选型和架构决策。