docs(zh-CN): sync Chinese docs with latest upstream changes (#304)

* docs(zh-CN): sync Chinese docs with latest upstream changes

* update

---------

Co-authored-by: neo <neo.dowithless@gmail.com>
This commit is contained in:
zdoc.app
2026-03-03 14:28:27 +08:00
committed by GitHub
parent adc0f67008
commit ada4cd75a3
114 changed files with 11161 additions and 4790 deletions

View File

@@ -1,21 +1,73 @@
# 更新代码地图
分析代码库结构并更新架构文档
分析代码库结构并生成简洁的架构文档
1. 扫描所有源文件的导入、导出和依赖关系
## 步骤 1扫描项目结构
2. 以以下格式生成简洁的代码地图:
* codemaps/architecture.md - 整体架构
* codemaps/backend.md - 后端结构
* codemaps/frontend.md - 前端结构
* codemaps/data.md - 数据模型和模式
1. 识别项目类型(单体仓库、单应用、库、微服务)
2. 查找所有源码目录src/, lib/, app/, packages/
3. 映射入口点main.ts, index.ts, app.py, main.go 等)
3. 计算与之前版本的差异百分比
## 步骤 2生成代码地图
4. 如果变更 > 30%,则在更新前请求用户批准
`docs/CODEMAPS/`(或 `.reports/codemaps/`)中创建或更新代码地图:
5. 为每个代码地图添加新鲜度时间戳
| 文件 | 内容 |
|------|----------|
| `architecture.md` | 高层系统图、服务边界、数据流 |
| `backend.md` | API 路由、中间件链、服务 → 仓库映射 |
| `frontend.md` | 页面树、组件层级、状态管理流 |
| `data.md` | 数据库表、关系、迁移历史 |
| `dependencies.md` | 外部服务、第三方集成、共享库 |
6. 将报告保存到 .reports/codemap-diff.txt
### 代码地图格式
使用 TypeScript/Node.js 进行分析。专注于高层结构,而非实现细节。
每个代码地图应为简洁风格 —— 针对 AI 上下文消费进行优化:
```markdown
# 后端架构
## 路由
POST /api/users → UserController.create → UserService.create → UserRepo.insert
GET /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
## 关键文件
src/services/user.ts (业务逻辑120行)
src/repos/user.ts (数据库访问80行)
## 依赖项
- PostgreSQL (主要数据存储)
- Redis (会话缓存,速率限制)
- Stripe (支付处理)
```
## 步骤 3差异检测
1. 如果存在先前的代码地图,计算差异百分比
2. 如果变更 > 30%,显示差异并在覆盖前请求用户批准
3. 如果变更 <= 30%,则原地更新
## 步骤 4添加元数据
为每个代码地图添加一个新鲜度头部:
```markdown
<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
```
## 步骤 5保存分析报告
将摘要写入 `.reports/codemap-diff.txt`
* 自上次扫描以来添加/删除/修改的文件
* 检测到的新依赖项
* 架构变更(新路由、新服务等)
* 超过 90 天未更新的文档的陈旧警告
## 提示
* 关注**高层结构**,而非实现细节
* 优先使用**文件路径和函数签名**,而非完整代码块
* 为高效加载上下文,将每个代码地图保持在 **1000 个 token 以内**
* 使用 ASCII 图表表示数据流,而非冗长的描述
* 在主要功能添加或重构会话后运行