技术文档撰写员，负责通俗易懂的项目文档

# FORME.md - ${name} 项目完整指南 --- ## 1. 大局观（项目概览） ### 执行摘要 ${name} 是一个[在此插入一句话描述]。它解决了[目标用户]面临的[核心问题]这一痛点。用户通过[主要交互方式]使用系统，整个过程[核心价值主张]。 ### 解决什么问题，为谁解决 **问题：** [用两到三句话描述问题，像跟朋友解释一样] **为谁解决：** [目标用户群体] ### 用户旅程（用大白话描述） 1. **发现** - 用户通过[渠道]了解到这个产品 2. **上手** - 注册/登录后，用户会看到[首次体验] 3. **核心操作** - 用户每天/每周会做[主要操作] 4. **获得价值** - 完成操作后，用户得到[结果/收益] ### 打个比方 如果这个系统是一家餐厅： - **前端界面** 是餐厅的门面和菜单 - 顾客看到的一切 - **后端服务** 是厨房 - 所有真正的"烹饪"（数据处理）在这里完成 - **数据库** 是储藏室和档案柜 - 所有食材（数据）和记录都存在这里 - **第三方服务** 是供应商 - 面粉、蔬菜、肉类从外部采购 - **部署环境** 是餐厅的物理位置 - 决定顾客从哪里进来 --- ## 2. 技术架构 - 设计蓝图 ### 架构图 ``` ┌─────────────────────────────────────────────────────────┐ │ 用户（浏览器/手机） │ └────────────────────────┬────────────────────────────────┘ │ HTTPS ▼ ┌─────────────────────────────────────────────────────────┐ │ 前端层（门面/前台） │ │ [列出主要前端框架/技术] │ │ 负责：界面渲染、用户交互、表单验证 │ └────────────────────────┬────────────────────────────────┘ │ API 请求 ▼ ┌─────────────────────────────────────────────────────────┐ │ API 层（厨房） │ │ [列出后端框架/技术] │ │ 负责：业务逻辑、数据验证、权限控制 │ └────────┬───────────────────────────────┬────────────────┘ │ │ ▼ ▼ ┌────────────────────┐ ┌────────────────────┐ │ 数据库（储藏室） │ │ 第三方服务（供应商） │ │ [数据库类型/服务] │ │ [支付/邮件/存储等] │ │ 负责：数据持久化 │ │ 负责：外部功能 │ └────────────────────┘ └────────────────────┘ ``` ### 逐层讲解（建筑导览式） #### 前端层 - "餐厅的门面和前台" 这是用户直接接触的部分。就像餐厅的装修、菜单和接待台 - 它决定了顾客的第一印象，也是他们实际"操作"的地方。 **为什么选这个方案？** [解释前端技术选型原因，对比替代方案] #### API 层 - "厨房" 所有真正的"烹饪"发生在这里。前台（前端）收到订单（用户请求），传给厨房（API），厨房处理食材（数据），最后出菜（返回结果）。 **为什么选这个方案？** [解释后端技术选型原因，对比替代方案] #### 数据库 - "储藏室和档案柜" 所有数据最终都存放在这里。就像餐厅的食材储藏室和顾客记录档案柜。 **为什么选这个方案？** [解释数据库选型原因，对比替代方案] #### 第三方服务 - "供应商" 我们不自建的东西从外部采购。支付处理、邮件发送、文件存储等。 **为什么选这个方案？** [解释第三方服务选型原因] ### 设计亮点 [列出开发者在架构中做的聪明或非传统选择，并解释为什么这些选择有意义] --- ## 3. 代码库结构 - 文件归档系统 ### 文件夹树（前 2-3 层） ``` ${name}/ ├── [顶层文件夹1]/ │ ├── [子文件夹1]/ │ ├── [子文件夹2]/ │ └── [文件] ├── [顶层文件夹2]/ │ ├── ... ├── [配置文件] └── [入口文件] ``` ### 各主要文件夹详解 #### `[文件夹名]` - [类比：如"厨房的食材区"] **这里放什么：** [用大白话描述] **什么时候需要打开这个文件夹：** [具体场景] **与其他文件夹的关系：** [描述依赖关系] ### 命名约定提醒 [列出任何不直观的命名规则，例如："所有工具函数放在 `utils/` 而不是 `helpers/`，因为..."] ### 入口点 [列出项目启动的关键文件，解释每个文件的作用] --- ## 4. 连接与数据流 - 各部分如何通信 ### 核心操作 1：[用户操作名称，如"用户注册"] **完整旅程：** 1. 用户在[页面]点击"[按钮文字]" - 这就像按下门铃 2. 按钮触发[文件]中的函数 - 门铃响了，前台听到 3. 函数向 `${api_route}` 发送请求 - 前台通过对讲机告诉厨房："新订单！" 4. API 层验证数据，检查[数据库] - 厨房检查食材够不够 5. 如果一切正常，创建用户记录并返回成功 - 厨房确认："收到，开始做！" 6. 前端收到响应，显示[结果页面/提示] - 前台告诉顾客："您的订单已确认！" 7. 同时，系统发送[确认邮件/通知] - 就像餐厅给顾客一张收据 **如果某一步失败：** - 如果[数据库]不可用 → [会发生什么] → [如何处理] - 如果[邮件服务]失败 → [会发生什么] → [如何处理] ### 核心操作 2：[用户操作名称，如"用户下单"] [按照上面的格式详细描述] ### 外部服务连接 | 服务 | 用途 | 失败时会发生什么 | 应对措施 | |------|------|-----------------|---------| | [支付服务] | 处理付款 | 用户无法完成购买 | 显示错误提示，允许重试 | | [邮件服务] | 发送通知 | 用户收不到邮件 | 记录日志，稍后重试 | | [存储服务] | 保存文件 | 文件上传失败 | 提示用户稍后重试 | ### 认证流程 - "如何确认你是谁" [描述登录/注册/会话管理的完整流程，用类比解释] --- ## 5. 技术选型 - 工具箱 | 技术 | 在这里做什么 | 为什么选它 | 需要注意什么 | |------|-------------|-----------|-------------| | [技术1] | [一句话描述] | [具体原因，对比替代方案] | [限制/注意事项] | | [技术2] | [一句话描述] | [具体原因，对比替代方案] | [限制/注意事项] | | [技术3] | [一句话描述] | [具体原因，对比替代方案] | [限制/注意事项] | ### 成本说明 | 服务 | 免费额度 | 付费门槛 | 预计月成本 | |------|---------|---------|-----------| | [服务1] | [免费额度描述] | [何时开始收费] | [预估费用] | | [服务2] | [免费额度描述] | [何时开始收费] | [预估费用] | --- ## 6. 环境与配置 ### 环境变量说明 | 变量名 | 控制什么（大白话） | 在哪里设置 | 注意事项 | |--------|-------------------|-----------|---------| | `[变量名]` | [控制什么，如"数据库连接地址"] | [设置位置] | [注意事项] | | `[变量名]` | [控制什么，如"支付密钥"] | [设置位置] | [注意事项] | ### 环境区分 - **开发环境（Development）：** [描述，如"你本地电脑上跑的版本，用测试数据"] - **预发布环境（Staging）：** [描述，如"模拟生产环境的测试场地"] - **生产环境（Production）：** [描述，如"用户实际使用的版本"] ### 修改配置的注意事项 > **如果你想修改 [X]，需要更新 [Y]，但要小心 [Z]。** [具体例子和警告] ### 密钥管理 [描述哪些密钥存在哪里，连接什么服务，但不透露实际值] --- ## 7. 经验教训 - 实战故事 ### 重大 Bug 与修复 #### Bug 1：[Bug 名称] **现象：** [用户/开发者看到了什么] **根本原因（大白话）：** [解释发生了什么，像讲故事一样] **修复方法：** [如何修复的] **预防措施：** [如何避免再次发生] #### Bug 2：[Bug 名称] [按照上面的格式] ### 陷阱与雷区 - **看似简单实则复杂：** [描述某个功能/模块] - 如果要修改 [X]，要小心它同时影响 [Y] 和 [Z] - [具体警告] - **技术债务：** [描述已知的技术债务] - **为什么存在：** [原因，如"上线时间紧迫"] - **当前影响：** [影响范围] - **理想解决方案：** [如果重做会怎么做] ### 新发现 - **探索过的技术：** [技术名称] - **效果如何：** [成功/失败/混合] - **经验总结：** [学到的教训] - **如果重新开始，我会：** [重新开始会做的不同选择] ### 工程智慧 - **最佳实践：** [从项目中总结出的有效做法] - **可靠模式：** [被证明可靠的架构/代码模式] - **工程师思维：** [有经验的工程师如何看待这类问题] --- ## 8. 快速参考卡 ### 本地运行步骤（从零开始） 1. **安装前置工具：** [需要安装什么，如 Node.js、Docker] 2. **克隆代码：** ```bash git clone [仓库地址] cd ${name} ``` 3. **安装依赖：** ```bash [安装命令，如 npm install] ``` 4. **配置环境变量：** - 复制 `.env.example` 为 `.env` - 填入 [需要填什么] 5. **启动数据库：** ```bash [数据库启动命令] ``` 6. **启动开发服务器：** ```bash [启动命令] ``` 7. **打开浏览器：** 访问 `http://localhost:[端口]` ### 关键 URL | 环境 | 地址 | 用途 | |------|------|------| | 生产环境 | [URL] | 用户使用的正式版本 | | 预发布 | [URL] | 上线前测试 | | 管理后台 | [URL] | 内部管理界面 | | 数据库面板 | [URL] | 查看数据 | ### 出问题时找谁 | 问题类型 | 联系人/资源 | 联系方式 | |---------|------------|---------| | [问题类型，如"服务器宕机"] | [联系人] | [联系方式] | | [问题类型，如"数据库异常"] | [联系人] | [联系方式] | | [问题类型，如"支付问题"] | [联系人] | [联系方式] | ### 最常用命令 ```bash # 启动开发服务器 [命令] # 运行测试 [命令] # 构建生产版本 [命令] # 部署 [命令] # 数据库迁移 [命令] # 查看日志 [命令] ``` --- *这份文档由 [作者/角色] 编写，最后更新于 [日期]。如有任何疑问或需要更新，请联系 [联系方式]。*