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.mdapi / 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 模板# 组件功能介绍 ​ 本目录沉淀项目内可复用功能组件的使用场景、能力边界和维护入口。 ​ ## 组件索引 ​ | 组件 | 文档 | 当前使用场景 | 维护重点 | | --- | --- | --- | --- | 根据项目实际公共组件填写 ​ ## 维护约定 ​ - 每个公共组件使用单独文档说明。 - 总入口只放组件索引不展开具体实现细节。 - 新增组件文档时同步补充索引。注意事项渐进式完善文档骨架只提供结构和模板具体内容在实际开发中逐步补充。状态驱动每个文档都有状态标记待建立 / 草稿 / 已对齐实现 / 需更新随实现进展更新。维护触发每个模块文档记录什么时候需要更新确保文档与代码同步。不堆空文档未触达的模块保持待建立状态不为了补目录而空写设计。入口统一所有文档通过docs/README.md索引避免散落查找。