当前位置： 首页 > news >正文

项目文档骨架生成器

news 2026/6/30 14:26:50 
description: 为新项目生成完整的文档骨架，包含代码规范、业务设计、全局设计、质量治理和组件文档目录结构。

为新项目生成完整的文档目录结构和模板文件，覆盖代码规范、业务模块设计、全局能力设计、质量治理和公共组件文档。

何时使用

  • 启动新项目需要建立文档体系时

  • 为已有项目补充缺失的文档结构时

  • 需要统一团队文档规范和模板时

文档体系总览

生成的文档目录结构如下：

docs/ ├── README.md # 文档总入口 ├── code-style/ │ ├── base-code-style-requirements.md # 基础代码风格要求 │ └── business-logic-layering-requirements.md # 业务逻辑分层规范 ├── design/ │ ├── README.md # 设计文档目录说明 │ └── modules/ # 功能模块设计（按需创建） │ └── <module-name>.md ├── global-design/ │ ├── README.md # 全局设计目录 │ ├── stores/ # 状态管理设计 │ │ └── README.md │ ├── domain/ # 领域层设计 │ │ └── README.md │ ├── services-http/ # HTTP 服务设计 │ │ └── README.md │ └── layouts/ # 布局设计 │ └── README.md ├── quality/ │ ├── README.md # 质量文档目录 │ ├── code-quality-roadmap.md # 质量治理路线图 │ └── unit-test-follow-ups.md # 测试问题跟进 └── components/ └── README.md # 公共组件文档

执行步骤

Step 1: 收集项目信息

向用户确认以下信息（如果用户未提供，使用合理默认值）：

信息用途默认值
项目名称文档标题和引用从 package.json 读取
项目定位README 描述"XXX 管理系统"
技术栈代码规范适用范围React + TypeScript + Ant Design
已有功能模块design/modules 初始列表空，后续逐步补充
全局能力点global-design 初始列表空，后续逐步补充

Step 2: 创建目录结构

按上述目录结构创建所有目录和文件。每个文件使用对应模板（见下方模板区）。

Step 3: 生成文档入口

创建docs/README.md作为文档总入口，包含：

  • 快速入口表格（场景 → 文档 → 说明）

  • 文档维护约定

Step 4: 生成代码规范

创建docs/code-style/下的两个核心文件：

  • base-code-style-requirements.md：目录职责、文件命名、行数限制、函数职责、参数传递、React props、类型规范、样式规范、质量门禁

  • business-logic-layering-requirements.md：api / services / store / hooks 分层原则

Step 5: 生成设计文档框架

创建docs/design/README.md，包含：

  • 维护原则

  • 状态说明（待建立 / 草稿 / 已对齐实现 / 需更新）

  • 功能模块索引表（初始为空或根据用户输入填充）

  • 模块设计文档结构建议

Step 6: 生成全局设计框架

创建docs/global-design/README.md及子目录入口，包含：

  • 目录定位

  • 维护原则

  • 全局功能点索引表

  • src/ 全局覆盖地图

Step 7: 生成质量文档框架

创建docs/quality/README.md及初始文件，包含：

  • 质量分类

  • 维护规则

  • 质量治理路线图模板

  • 测试问题跟进模板

Step 8: 生成组件文档框架

创建docs/components/README.md，包含：

  • 使用场景

  • 组件索引表

  • 维护约定

模板区

docs/README.md 模板

# {PROJECT_NAME} 文档总入口 ​ 本目录收敛 {PROJECT_NAME} 的协作文档、设计记录和验收资料。项目运行、构建、质量检查等基础说明以根目录 `README.md` 为准。 ​ ## 快速入口 ​ | 场景 | 文档 | 说明 | | --- | --- | --- | | 项目启动与开发 | [`../README.md`](../README.md) | 项目定位、本地开发、运行模式、构建部署和质量检查。 | | 基础代码风格要求 | [`code-style/base-code-style-requirements.md`](./code-style/base-code-style-requirements.md) | 新增代码和被改动旧文件必须遵守的职责边界、命名、行数、参数、组件和样式规则。 | | 业务逻辑分层规范 | [`code-style/business-logic-layering-requirements.md`](./code-style/business-logic-layering-requirements.md) | 新功能、较大业务改动或重构评估需要参考的分层原则。 | | 质量文档目录 | [`quality/README.md`](./quality/README.md) | 质量问题分类、总路线图、测试跟进和专项方案入口。 | | 全局设计目录 | [`global-design/README.md`](./global-design/README.md) | 需要独立设计说明的全局能力设计与覆盖索引。 | | 设计文档目录 | [`design/README.md`](./design/README.md) | 按功能模块管理设计文档。 | | 组件功能介绍 | [`components/README.md`](./components/README.md) | 公共功能组件的使用场景、能力边界和维护入口。 | ​ ## 文档维护约定 ​ - 新增正式协作文档优先放入 `docs/`，并同步补充到本入口。 - 全局能力设计放入 `docs/global-design/`，覆盖需要独立设计说明的横切源码。 - 功能模块设计放入 `docs/design/`，按功能模块逐步完善。 - 个人备忘、临时记录应明确标注为非正式文档。

docs/code-style/base-code-style-requirements.md 模板骨架

# 基础代码职责与风格要求 ​ 本文档定义 {PROJECT_NAME} 前端项目后续新增代码和改动代码必须遵守的基础职责边界、组织方式和可读性规则。 ​ ## 适用范围 ​ - 所有新增代码必须严格遵守本文档规则。 - 所有改动到的旧文件也必须按本文档处理。 - 评审时以本文档作为风格门禁依据。 ​ ## 目录职责 ​ （根据项目实际目录结构填写） ​ ## 文件命名与入口 ​ - 所有源码文件统一使用 kebab-case。 - React 组件名、类型名和 class 名使用 PascalCase，但文件名必须使用 kebab-case。 - 页面模块统一使用目录入口：`src/pages/<page-key>/index.tsx`。 ​ ## 文件行数 ​ - 普通 `.ts`、`.tsx` 文件建议不超过 300 行。 - 页面入口 `index.tsx` 建议不超过 500 行。 - 仓储、store 文件建议不超过 600 行。 - 单个样式文件建议不超过 800 行。 ​ ## 函数单一职责 ​ - 一个函数只做一类事情。 - 普通函数建议不超过 80 行，超过 120 行视为必须拆分。 - React 组件建议不超过 180 行，页面组件建议不超过 300 行。 ​ ## 参数传递 ​ - 1 到 2 个参数时优先使用位置参数。 - 3 个及以上参数必须改为对象参数，并定义命名类型。 ​ ## React props ​ - 组件 props 超过 6 个时，必须定义显式 `Props` 类型。 - props 超过 8 个时，必须评估拆分组件或分组 props。 ​ ## 类型与数据模型 ​ - 接口 DTO、store 状态、页面展示结构分开命名，不共用一个大类型。 - 禁止使用 `any` 绕过边界。 ​ ## 样式 ​ - UI 组件优先使用组件库自带组件。 - 页面或组件专属样式必须就近放入对应模块目录。 - 颜色必须通过 CSS 变量或 token 表达。 ​ ## 质量门禁 ​ 提交前必须完成 `typecheck`、`lint` 和 `test` 校验。

docs/code-style/business-logic-layering-requirements.md 模板骨架

# 业务逻辑分层规范 ​ 本文档定义 {PROJECT_NAME} 前端项目在 `api`、`services`、`store`、`hooks` 之间的业务逻辑分层原则。 ​ ## 分层模型 ​

pages/components → hooks/stores hooks → services/store selectors/actions stores → services services → api api → HTTP 客户端

​ ## 各层职责 ​ ### api 层 - 只封装后端请求，不组织业务流程。 - 不读写 UI 状态或全局状态。 ​ ### services 层 - 组织业务流程和用例编排。 - 不保存 UI 状态。 ​ ### stores 层 - 保存需要保留的页面状态、全局状态、跨页面共享状态。 - 不放接口 mock 数据、大段 UI 派生文案或 JSX。 ​ ### hooks 层 - 管理页面临时数据、请求状态、副作用编排。 - 不保存跨页面全局状态。 ​ ## 依赖方向 ​ （根据项目实际情况定义推荐和禁止的依赖方向）

docs/design/README.md 模板

# 设计文档目录 ​ 本目录按功能模块管理 {PROJECT_NAME} 的设计文档。设计文档不要求一次性补齐；每次开发、调整或复盘涉及某个模块时，同步创建或更新对应模块的设计文档。 ​ ## 维护原则 ​ - 设计文档按功能模块拆分，不按临时需求、技术层或零散组件堆放。 - 未进入实施或本次未触达的模块可以保持待建立状态。 - 首次进入某个模块时，先创建对应模块设计文档。 - 已有模块发生变化时，同步更新对应设计文档。 ​ ## 状态说明 ​ | 状态 | 含义 | | --- | --- | | 待建立 | 还没有正式模块设计文档。 | | 草稿 | 已记录初版设计，但仍缺少关键流程、边界或代码落点。 | | 已对齐实现 | 文档已覆盖当前实现，并能指导后续维护。 | | 需更新 | 代码或业务口径已变化，文档需要跟进修订。 | ​ ## 功能模块索引 ​ | 功能模块 | 建议文档路径 | 当前状态 | 维护触发 | | --- | --- | --- | --- | （根据项目实际功能模块填写） ​ ## 模块设计文档结构 ​ 新建模块设计文档时，建议包含： ​ - 模块目标与适用范围 - 业务角色、权限和正式状态边界 - 页面结构、核心操作和交互路径 - 状态流转、确认链和异常处理 - 数据来源、接口字段和 mock/API 差异 - 关键代码入口、测试覆盖和回归关注点 - 当前取舍、未决问题和后续补充计划

docs/design/modules/<module>.md 模板

# {MODULE_NAME}设计 ​ 状态：草稿 最近更新：{DATE} ​ ## 模块目标与范围 ​ （描述本模块的职责边界） ​ 本设计覆盖： - ... ​ 不在本设计内展开： - ... ​ ## 设计原则 ​ - ... ​ ## 页面结构 ​ （页面布局、分区、组件映射） ​ ## 核心流程 ​ （主要业务流程、状态流转） ​ ## 数据设计 ​ （状态管理、接口字段、mock 差异） ​ ## 关键代码入口 ​ | 职责 | 文件 | | --- | --- | （根据实际代码填写） ​ ## 测试与回归关注 ​ - ...

docs/global-design/README.md 模板

# 全局设计目录 ​ 状态：草稿 最近更新：{DATE} ​ ## 目录定位 ​ 本目录维护 {PROJECT_NAME} 的全局设计资源。全局设计不属于功能模块设计，也不替代公共组件说明。 ​ ## 维护原则 ​ - 一个全局功能点一个独立文档。 - 每个功能点文档必须说明：做什么、什么时候使用、怎么实现。 - `src/pages/` 归入功能模块设计。 - `src/components/` 归入公共组件说明。 ​ ## 全局功能点索引 ​ | 功能点 | 文档 | 状态 | 做什么 | 什么时候使用 | | --- | --- | --- | --- | --- | （根据项目实际全局能力填写） ​ ## 与其他文档目录的关系 ​ | 目录 | 职责 | | --- | --- | | `docs/global-design/` | 全局能力设计。 | | `docs/design/modules/` | 业务功能模块设计。 | | `docs/components/` | 公共组件说明。 |

docs/quality/README.md 模板

# 质量文档目录 ​ 本目录收敛质量治理相关文档。代码风格和职责边界规范放在 `docs/code-style/`；质量目录只记录当前质量问题、分类和待落实提醒。 ​ ## 文档入口 ​ | 文档 | 定位 | 适用场景 | | --- | --- | --- | | `code-quality-roadmap.md` | 质量治理总路线图 | 查看质量问题分类、优先级和建议执行顺序。 | | `unit-test-follow-ups.md` | 测试暴露问题跟进 | 触达关联模块前核对当前仍存在的测试失败。 | ​ ## 维护规则 ​ - 新增质量问题先归入分类，再决定是否进入路线图。 - 测试暴露但需要后续确认的问题放入 `unit-test-follow-ups.md`。 - 已验证通过的问题应移除或替换为当次仍失败的问题。

docs/components/README.md 模板

# 组件功能介绍 ​ 本目录沉淀项目内可复用功能组件的使用场景、能力边界和维护入口。 ​ ## 组件索引 ​ | 组件 | 文档 | 当前使用场景 | 维护重点 | | --- | --- | --- | --- | （根据项目实际公共组件填写） ​ ## 维护约定 ​ - 每个公共组件使用单独文档说明。 - 总入口只放组件索引，不展开具体实现细节。 - 新增组件文档时同步补充索引。

注意事项

  1. 渐进式完善：文档骨架只提供结构和模板，具体内容在实际开发中逐步补充。

  2. 状态驱动：每个文档都有状态标记（待建立 / 草稿 / 已对齐实现 / 需更新），随实现进展更新。

  3. 维护触发：每个模块文档记录"什么时候需要更新"，确保文档与代码同步。

  4. 不堆空文档：未触达的模块保持"待建立"状态，不为了补目录而空写设计。

  5. 入口统一：所有文档通过docs/README.md索引，避免散落查找。

http://www.jsqmd.com/news/1096444/

相关文章：

  • 云南历史类455-515分各分数段怎么填？云南工商学院从征集到稳妥都值得关注
  • Spring AOP（XML配置版）：代理机制与拦截器
  • 【硬件设计实战】JTAG接口上下拉电阻配置全解析：从标准到芯片手册
  • 【小白也能轻松玩转龙虾】虾壳云一键部署教程，OpenClaw v2.7.9 可视化安装全过程（附最新安装包）
  • 2026年企业级AI API聚合平台选型指南：六大主流中转服务横向对比与技术评测
  • 终极音乐解放：3分钟掌握ncmdumpGUI，永久解锁网易云音乐加密文件
  • Kali Linux实战：SQL注入与XSS漏洞攻防演练
  • 从拒稿到录用：我的IEEE TII投稿实战复盘与避坑指南
  • 误删微信聊天记录不用愁，全套官方恢复教程，文末科普第三方渠道
  • 《重启日记》第十四周｜主业忙碌，更新放缓：流量起伏无碍长期沉淀
  • 泰国华商出海数字化选型解析：国内大厂、本土软件与出海专属系统对比(批发 / 零售业态专属)
  • 别急着追Multi-Agent，先想清楚这三个问题
  • GPU内存完整性验证：MemtestCL架构解析与实战配置指南
  • 从状态访问到动作决策：占用度量如何量化策略的探索足迹
  • 这个级别的配置两万，别碰积家翻转古董表，单看这处表壳加工公差就会吃亏
  • d2s-editor：重新定义暗黑破坏神2存档编辑体验的开源工具
  • 免费开源项目文档：基于HSV颜色空间和形态学特征的火灾与烟雾智能检测系统
  • AI正在变成特权，你还配用吗 - 微元算力(weytoken)
  • 【银河麒麟V10】vsFTPd服务实战：从零部署到安全加固全攻略
  • 【UE5蓝图实战】从零实现高效物体框选：原理、优化与多类型Actor筛选
  • Python实战：打造阴阳师御魂副本智能挂机脚本，兼顾效率与防检测
  • Docker 从零到实战：Windows Linux 安装、命令与配置全攻略
  • Python 多源行情数据冲突排查：symbol、timestamp、字段口径和原始返回校验
  • 龙口让人放心防水公司特点
  • openEuler HPC Runner性能优化秘籍：提升HPC应用运行效率的10个技巧
  • 暗黑破坏神2存档编辑器终极指南：零基础学会角色自定义
  • C#：XmlNodeList
  • 三步完成Beyond Compare 5永久激活：开源密钥生成器完整指南
  • 点胶点钻设备现场调试笔记：压电阀与视觉定位系统的工艺适配分析
  • 别让 AI 误读你的资产：用推送接口构建带“防伪签名”的 GEO 数据源