frontend-tech-doc-guide
# 一、文档结构规则（必须严格遵守）
## 1. 标题层级规则
文档标题层级 **必须严格按以下结构生成，不允许跳级**：
```
# 文档标题
# 一、需求认知
需求 PRD：xx
飞书项目：xx
后端文档：xx
UI 设计稿：xx
- 需求背景
- 需求目标
- 核心/特殊改动点
# 二、项目排期
<!-- 评估需求开发内容量，根据复杂度和时间成本，合理分配项目排期。 -->
# 三、功能流程
<!-- 全部使用 mermaid 流程图 表示 -->
## 1. 页面流程
## 2. 功能流程
## ...其他流程
# 四、需求拆分
<!-- 详细描述需求功能模块，包括前端需求点以及所对应的后端接口。 -->
<!-- 需要考虑到边界情况以及异常处理。 -->
# 五、业务埋点 & Sentry 监控
<!-- 埋点信息从需求 PRD 中获得，关注参数，触发时机 -->
<!-- 埋点需要生成 mermaid 操作路径 -->
<!-- 特殊报错需要使用 Sentry 监控输出 -->
# 六、数据链路
<!-- 使用 mermaid 绘制用户在页面的活动链路 -->
# 七、提测信息
<!-- 使用表格格式，表头：模块、内容、备注 -->
<!-- 第一列：提测项目，提测环境 -->
# 八、验收与上线
<!-- 使用表格格式，表头：项目，上线 TAG -->
# 九、待确认问题
<!-- 使用表格格式，表头：问题，结论 -->
```
# 二、章节生成顺序（防止内容错位）
AI **必须严格按以下顺序生成内容**：
1. 需求认知
2. 项目排期
3. 功能流程
4. 需求拆分
5. 业务埋点 & Sentry 监控
6. 数据链路
7. 提测信息
8. 验收上线
9. 待确认问题
### 关键约束
生成时必须遵守：
* **不得提前生成后续章节内容**
* **不得回写前文**
* **不得复制后文内容到前文**
例如禁止出现：
```
开头出现：
第7章内容
第8章内容
```
若模型生成时出现重复章节，必须：
* 删除重复段
* 保留第一次出现的位置
---
# 三、段落排版规则（提升可读性）
AI 生成内容时 **禁止连续长文本块**。
每段说明 **必须拆分为以下结构之一**：
### 1 优先使用列表
错误示例：
```
系统需要完成登录、鉴权、资格校验、任务获取、抽奖逻辑等功能。
```
正确示例：
```
系统主要流程包括：
- 登录
- 身份鉴权
- 资格校验
- 任务获取
- 抽奖执行
```
---
### 2 技术描述必须结构化
统一使用 **模块结构**：
```
模块名称
- 功能说明
- 接口
- 关键逻辑
- 依赖
```
示例：
```
### 积分活动模块
功能：
- 展示用户积分
- 提供抽奖入口
接口：
- getUserPoints
- drawLottery
关键逻辑：
- 未登录先触发登录
- 积分不足提示
```
---
# 四、流程章节规范（必须包含 Mermaid）
流程章节 **必须包含 Mermaid 图**。
示例：
```mermaid
flowchart TD
Entry[活动入口] --> Login{是否登录}
Login -- 否 --> Auth[手机号授权]
Login -- 是 --> Check[资格校验]
Check --> Task[任务列表]
Task --> Draw[抽奖]
Draw --> Result[结果弹窗]
```
生成规则：
* Mermaid **只允许出现一次代码块**
* 使用 `<br/>` 换行
* 不允许使用 `\n`
---
# 五、模块拆分规则
模块章节必须按以下格式生成：
```
## 模块名称
功能：
- xxx
- xxx
核心逻辑：
- xxx
- xxx
接口：
| 接口 | 说明 |
|----|----|
| getTask | 获取任务 |
| drawLottery | 抽奖 |
依赖：
- 风控接口
- 奖品接口
```
禁止生成 **长段技术说明文字**。
---
# 六、埋点章节格式
必须使用表格。
示例：
| 事件 | code | 触发时机 |参数|
| ---- | ------------ | ---- |----|
| 页面曝光 | page_view | 页面加载 |...|
| 抽奖点击 | draw_click | 点击抽奖 |...|
| 抽奖成功 | draw_success | 返回中奖 |中奖结果|
---
# 七、提测信息格式
表格结构
# 八、AI 生成质量规则（重点）
AI 在生成文档前必须执行：
### 1 章节检查
确认存在以下章节：
* 需求认知
* 项目排期
* 功能流程
* 需求拆分
* 业务埋点 & Sentry 监控
* 数据链路
* 提测信息
* 验收上线
* 待确认问题
缺一不可。
---
### 2 排版检查
确保：
* 无连续超过 **5 行纯文本段落**
* 必须包含
* 列表
* 表格
* Mermaid
---
# 九、AI 输出限制
AI 输出文档时必须遵守：
1 不输出解释
只输出 Markdown 文档
2 不输出多版本
只输出最终版本
3 不输出空章节
无内容时写：
```
待补充
```
---
# 十、推荐文档标题格式
```
【YYMMDD】活动简称-前端技术方案
```
示例：
```
【260320】春季直播活动-前端技术方案
```
---
# 十一、生成目标
AI 生成的文档必须达到：
* Markdown 层级正确
* 飞书渲染结构稳定
* 章节顺序正确
* 信息结构化
* 可读性高
否则视为生成失败。
标签
skill
ai
