Add a scaffold script that replaces the bq prefix with the new project name.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
bql
2026-10-27 22:46:06 +08:00
commit bc84c95a89
128 changed files with 9700 additions and 0 deletions

View File

@@ -0,0 +1,68 @@
# 撰写总则
## 目录
- [文档分三类](#文档分三类)
- [每篇文档都写目录](#每篇文档都写目录)
- [图中只用项目词条](#图中只用项目词条)
- [图只画本层](#图只画本层)
- [功能模块何时拆开](#功能模块何时拆开)
- [文件名](#文件名)
- [示例与正式文档](#示例与正式文档)
## 文档分三类
| 文档 | 位置 | 正文 |
| ---- | ---------------------------------- | ---------------------------------------- |
| 项目架构 | `doc/项目架构.md`,全库一篇 | 目录结构(到 `features/[feature]`)、模块定义、功能模块之间的业务数据流 |
| 基础应用 | `doc/基础应用/`,`src/app` 下,一个目录一篇 | 功能定义、使用示例、该应用内部的数据流与时序 |
| 功能模块 | `doc/功能模块/`,`src/features` 下一个目录一组 | 模块内目录、功能定义、核心业务层与核心模型、核心业务时序图 |
`src/app` 下的每个目录是一个基础应用。`src/features` 下的每个目录是一个功能模块。
章节的写法分别见:
- [项目架构文档撰写说明](./项目架构文档撰写说明.md)
- [基础应用文档撰写说明](./基础应用/基础应用文档撰写说明.md)
- [功能模块文档撰写说明](./功能模块/功能模块文档撰写说明.md)
## 每篇文档都写目录
标题下第一段是目录,标题为「目录」。条目与正文标题一致,并链到对应标题。拆出去的业务文档写进父文档目录,链到文件。
撰写说明、示例、正式文档都要有目录。
## 图中只用项目词条
Mermaid 的节点、参与者、箭头文字只用仓库里的目录名、类名、方法名、字段名。中文说明写在图外的正文里。
## 图只画本层
项目架构只画 `home`、`security`、`project`、`editor` 之间的业务数据。不画 `session`、`network`、`db`、`routes` 这些基础应用,也不画时序。
基础应用只画该目录内部的类和函数。不画功能模块的调用链,也不把其他基础应用的内部步骤画进来。调用方可以出现在使用示例的代码里。时序图已经能说明这条行为时,不再画数据流图。
功能模块的时序写在功能模块文档。那里不展开基础应用内部步骤。
## 功能模块何时拆开
一条主业务时,时序图写在该模块主文档里。
同一模块有多条要分开讲述的事件业务时,为每条业务另写一篇,放在该模块目录下。主文档保留目录结构、功能定义、核心业务层与核心模型,并用目录链到各业务文档。编辑器的打开、绘制、撤销与重做按这个方式拆开。
方法定义写在主文档的核心业务层。业务文档写该业务的定义和时序图,并点名用到的方法。
## 文件名
- 基础应用:`中文名(目录名).md`,例如 `会话(session).md`。
- 功能模块主文档:`模块名(目录名).md`,例如 `编辑器模块(editor).md`。
- 拆出的业务文档:放在同一模块目录,用业务名作文件名,例如 `绘制.md`。
- 说明与示例只放在 `doc/文档撰写说明与示例/`。
## 示例与正式文档
示例用来对齐章节和粒度,正式文档另写。类名、方法、目录以当时仓库为准;代码变了就改正式文档。