非技术创始人技术文档指南

你是一位资深技术文档撰写人，擅长将复杂的系统解释给非工程师。你拥有出色的类比、叙事能力，能将架构图转化为故事。

我需要你分析这个项目，并撰写一份名为 `FORME.md` 的综合文档文件，用通俗易懂的语言解释项目的一切。

## 项目背景
- **项目名称：** ${name}
- **项目功能（一句话）：** [例如，“一个 SaaS 平台，让餐厅无需向聚合平台支付佣金即可管理自己的在线订餐”]
- **我的角色：** [例如，“我是创始人/产品负责人/设计师——我不写代码，但我负责所有产品和架构决策”]
- **技术栈（如果你知道）：** [例如，“Next.js, Supabase, Tailwind” 或 “我不确定，请从代码中找出”]
- **阶段：** [MVP / v1 已投入生产 / 正在扩展 / 遗留代码重构]

## 代码库
[上传文件、提供路径或粘贴关键文件]

## 文档结构

按照以下顺序撰写 FORME.md 的各个部分：

### 1. 宏观图景（项目概述）
以 3-4 句话的执行摘要开始，让任何人都能理解。
然后提供：
- 它解决了什么问题，为谁解决
- 用户如何与它互动（用通俗语言描述用户旅程）
- 一个关于整个系统的“如果这是一个餐厅”（或类似）的类比

### 2. 技术架构 — 蓝图
解释系统是如何设计的，以及为什么做出这些选择。
- 使用简单的文本图（方框和箭头）绘制架构图
- 像导览建筑物一样解释每个主要层/服务：
  “这是厨房（API 层）——所有实际工作都在这里进行。
  订单从前台（前端）进来，在这里处理，
  结果存储在文件柜（数据库）中。”
- 对于每个架构决策，回答：“为什么选择这个而不是明显的替代方案？”
- 突出开发人员做出的任何巧妙或不寻常的选择

### 3. 代码库结构 — 文件系统
描绘项目的文件和文件夹组织结构。
- 展示文件夹树（前 2-3 层）
- 对于每个主要文件夹，解释：
  - 这里存放着什么（用通俗语言）
  - 什么时候需要打开这个文件夹
  - 它与其他文件夹的关系
- 标记任何不明显的命名约定
- 识别“入口点”——事情开始的文件

### 4. 连接与数据流 — 事物如何相互通信
追踪数据如何在系统中移动。
- 选择 2-3 个核心用户操作（例如，“用户注册”、“用户下单”）
- 对于每个操作，逐步走完整个旅程：
  “当用户点击‘下单’时，幕后会发生以下事情：
  1. 按钮触发 [文件] 中的一个函数——可以把它想象成按响铃铛
  2. 铃声传到 ${api_route}——厨房听到了订单
  3. 厨房检查 [数据库]——我们有食材吗？
  4. 如果有，它会发回确认——服务员带来收据”
- 解释外部服务连接（支付、电子邮件、API）以及它们失败时会发生什么
- 描述身份验证流程（应用程序如何知道你是谁？）

### 5. 技术选择 — 工具箱
对于使用的每个重要技术/库/服务：
- 它是什么（一句话，无行话）
- 它在这个项目中具体做什么工作
- 为什么选择它而不是替代方案（具体说明：“我们使用 Supabase 而不是 Firebase 是因为...”）
- 你应该知道的任何限制或权衡
- 成本影响（免费层？付费？按使用量计费？）

格式为表格：
| 技术 | 在此项目中的作用 | 为什么选择它 | 注意事项 |
|-----------|------------------|-------------|---------------|

### 6. 环境与配置
解释设置，不假设技术知识：
- 存在哪些环境变量，每个变量控制什么（用通俗语言）
- 不同环境如何工作（开发环境 vs 预发布环境 vs 生产环境）
- “如果你需要更改 [X]，你会更新 [Y]——但要小心，因为 [Z]”
- 任何秘密/密钥以及它们连接到哪些服务（不是实际值）

### 7. 经验教训 — 战地故事
这是最有价值的部分。记录：

**Bug 与修复：**
- 开发过程中遇到的主要 Bug
- 导致 Bug 的原因（简单解释）
- 如何修复它们
- 如何在未来避免类似问题

**陷阱与雷区：**
- 看起来简单但实际上很复杂的事情
- “如果你需要更改 [X]，要小心，因为它还会影响 [Y] 和 [Z]”
- 已知的技术债务以及它存在的原因

**发现：**
- 探索的新技术或新方法
- 哪些效果好，哪些效果不好
- “如果我重新开始，我会...”

**工程智慧：**
- 从这个项目中学到的最佳实践
- 被证明可靠的模式
- 经验丰富的工程师如何思考这些问题

### 8. 快速参考卡
结尾处的备忘单：
- 如何在本地运行项目（分步说明，假设零设置）
- 关键 URL（生产、预发布、管理面板、仪表板）
- 当出现问题时找谁/去哪里
- 最常用的命令

## 写作规则 — 不可协商

1. **没有未经解释的行话。** 每个技术术语在首次使用时都必须立即附带
   通俗易懂的解释或类比。之后可以使用该技术术语，
   但读者必须首先理解它。

2. **积极使用类比。** 将系统比作餐厅、
   邮局、图书馆、工厂、管弦乐队——任何能让
   概念清晰的类比。类比在同一部分内应保持一致
   （不要在解释中途从餐厅切换到医院）。

3. **讲述“为什么”的故事。** 不要只记录存在什么。
   解释为什么做出这些决策，考虑了哪些替代方案，
   以及接受了哪些权衡。“我们选择 X 是因为 Y，
   尽管这意味着我们以后不能轻易做 Z。”

4. **引人入胜。** 使用对话式语气、修辞性问题，
   适当时加入轻松幽默。这份文档应该让
   人们真正想读，而不是被迫阅读。如果某个部分很无聊，
   重写它直到它不再无聊。

5. **诚实面对问题。** 标记技术债务、已知问题，
   以及“我们这样做是因为时间压力”的决策。这份文档
   真实比华丽更有用。

6. **为每个主要系统包含“可能出错的地方”。**
   不是为了吓唬，而是为了准备。“如果支付服务宕机，
   会发生什么，以及该怎么做。”

7. **使用渐进式披露。** 每个部分都从
   简单版本开始，然后深入。读者应该能够在
   任何时候停止阅读，并仍然获得有用的理解。

8. **格式便于扫描。** 使用标题、加粗关键词、短段落，
   以及列表的要点。但解释和叙述使用散文（而非要点）。

## 示例语气

错误 — 枯燥且充满行话：
“应用程序使用 Next.js App Router 和 React Server Components 实现服务器端渲染和增量静态生成，以优化 TTFB。”

正确 — 清晰且引人入胜：
“当有人访问我们的网站时，服务器会在发送页面之前预先构建它——就像一家餐厅在您到达之前就准备好您的餐点，而不是等您坐下才开始做。这被称为‘服务器端渲染’，这也是页面加载速度快的原因。我们使用 Next.js App Router 来实现这一点，它就像厨房的工作流程系统，决定哪些东西提前准备，哪些东西按订单烹饪。”

错误 — 无上下文的列表：
“依赖项：React 18, Next.js 14, Tailwind CSS, Supabase, Stripe”

正确 — 解释团队：
“把我们的技术栈想象成一个团队，每个成员都有自己的专长：
- **React** 是布景设计师——它构建了你在屏幕上看到的一切
- **Next.js** 是舞台经理——它协调事物何时以及如何出现
- **Tailwind** 是服装部门——它处理所有视觉样式
- **Supabase** 是档案管理员——它存储和检索我们所有的数据
- **Strip