universal-dev-standards 5.16.0 → 6.0.0

package/bundled/locales/zh-CN/options/code-review/pr-review.md

@@ -0,0 +1,167 @@
+---
+source: options/code-review/pr-review.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# Pull Request 审查
+
+> **语言**: [English](../../../../options/code-review/pr-review.md) | 简体中文
+
+**上层标准**: [Code Review Checklist](../../core/code-review-checklist.md)
+
+---
+
+## 概览
+
+Pull Request（PR）审查是传统的异步代码审查流程，在合并前先提交变更以供审查。它提供有文档记录的审计轨迹，并且很适合分布式团队。
+
+## 最适用于
+
+- 横跨不同时区的分布式团队
+- 异步工作流程
+- 需要审计轨迹的项目
+- 开源项目
+- 合规与法规要求
+
+## 工作流程
+
+### 1. 创建 Pull Request
+
+**作者职责：**
+- 撰写清晰、具描述性的 PR 标题
+- 加入完整的描述
+- 链接相关 issue
+- 指派适当的 reviewer
+- 确保 CI 检查通过
+
+### 2. 审查
+
+**Reviewer 职责：**
+- 检查功能与正确性
+- 审查代码质量与风格
+- 验证安全考量
+- 必要时在本地执行测试
+- 提供建设性的反馈
+
+### 3. 回应反馈
+
+**作者职责：**
+- 处理所有反馈意见
+- 以新的 commit 推送修正
+- 回复评论
+- 准备好后请求重新审查
+
+### 4. Approve 并合并
+
+**最后步骤：**
+- 取得必要的 approval
+- 确保所有检查通过
+- 使用约定的策略合并
+- 删除 feature 分支
+
+## 审查检查清单
+
+### 功能
+
+- [ ] 代码是否正常运作？
+- [ ] 是否处理了边界情况？
+- [ ] 错误处理是否适当？
+
+### 代码质量
+
+- [ ] 代码是否易读？
+- [ ] 函数是否聚焦（单一职责）？
+- [ ] 是否有代码重复？
+- [ ] 命名是否具描述性？
+
+### 安全
+
+- [ ] 是否有 injection 漏洞？
+- [ ] 输入是否经过验证？
+- [ ] 是否有凭证泄露？
+- [ ] 依赖包是否安全？
+
+### 测试
+
+- [ ] 是否有足够的测试？
+- [ ] 测试是否涵盖边界情况？
+- [ ] 测试是否易读且易维护？
+
+## 评论惯例
+
+### 前缀风格
+
+| 前缀 | 含义 | 是否阻挡 |
+|--------|---------|----------|
+| `[REQUIRED]` | 合并前必须修正 | 是 |
+| `[SUGGESTION]` | 考虑修改 | 否 |
+| `[QUESTION]` | 需要澄清 | 否 |
+| `[NIT]` | 细微的风格问题 | 否 |
+| `[PRAISE]` | 做得好 | 否 |
+
+### Emoji 风格
+
+| Emoji | 含义 |
+|-------|---------|
+| ❗ | 阻挡性问题 |
+| ⚠️ | 建议 |
+| 💡 | 想法 |
+| ❓ | 问题 |
+| 👍 | 赞赏 |
+
+## PR 模板
+
+```markdown
+## Summary
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Manual testing performed
+
+## Checklist
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Documentation updated if needed
+```
+
+## 规则
+
+| 规则 | 描述 | 优先级 |
+|------|-------------|----------|
+| 及时审查 | 在 24 小时内审查 | Recommended |
+| 建设性反馈 | 说明原因，而不只是说明内容 | Required |
+| Approve 前先测试 | 确保所有测试通过 | Required |
+| 最少 reviewer 数 | 至少需要一个 approval | Required |
+
+## 与其他方法的比较
+
+| 方面 | PR Review | Pair Programming |
+|--------|-----------|------------------|
+| 时机 | 异步 | 实时 |
+| 反馈 | 延迟 | 立即 |
+| 知识分享 | 中等 | 高 |
+| 文档记录 | 较高（PR 评论） | 较低 |
+| 可扩展性 | 高 | 有限 |
+| 远程友好度 | 容易 | 具挑战性 |
+
+## 相关选项
+
+- [Pair Programming](./pair-programming.md) - 实时协作审查
+- [Automated Review](./automated-review.md) - 工具辅助审查
+
+---
+
+## 授权
+
+本文档以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权发布。
+
+**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-CN/options/documentation/api-docs.md

@@ -0,0 +1,191 @@
+---
+source: options/documentation/api-docs.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# API Documentation
+
+> **语言**: [English](../../../../options/documentation/api-docs.md) | 简体中文
+
+**Parent Standard**: [Documentation Structure](../../core/documentation-structure.md)
+
+---
+
+## 概览
+
+API 文档为集成你 API 的开发者提供结构化的参考资料。它涵盖 endpoint 规格、authentication、request/response 格式以及错误处理。
+
+## 最适用于
+
+- REST APIs
+- GraphQL APIs
+- SDK／Library 文档
+- 公开 API
+- 开发者门户
+
+## 文档格式
+
+### OpenAPI (Swagger)
+
+| 方面 | 细节 |
+|--------|---------|
+| **Versions** | 3.0、3.1 |
+| **File Types** | `.yaml`、`.json` |
+| **Best For** | REST APIs |
+| **Tools** | Swagger UI、Redoc、Stoplight |
+
+### GraphQL Schema
+
+| 方面 | 细节 |
+|--------|---------|
+| **File Types** | `.graphql`、`.gql` |
+| **Best For** | GraphQL APIs |
+| **Tools** | GraphQL Playground、Apollo Studio |
+
+### AsyncAPI
+
+| 方面 | 细节 |
+|--------|---------|
+| **Versions** | 2.x、3.x |
+| **Best For** | 事件驱动 API |
+| **Tools** | AsyncAPI Studio |
+
+## OpenAPI 结构示例
+
+```yaml
+openapi: "3.1.0"
+info:
+  title: API Name
+  version: "1.0.0"
+  description: API description
+
+servers:
+  - url: https://api.example.com/v1
+
+paths:
+  /users:
+    get:
+      summary: List users
+      responses:
+        "200":
+          description: Success
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+```
+
+## 文档元素
+
+### Required
+
+- Endpoint URL
+- HTTP method
+- Request 参数
+- Response 格式
+- Error codes
+- Authentication
+
+### Recommended
+
+- 代码示例（多种语言）
+- Rate limits
+- 分页细节
+- Changelog／versioning
+
+### Optional
+
+- Try-it-out console
+- SDKs
+- Postman collections
+
+## Endpoint 文档示例
+
+```markdown
+## Create User
+
+Creates a new user account.
+
+**Endpoint:** `POST /users`
+
+**Authentication:** Bearer token required
+
+### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | User's full name |
+| email | string | Yes | Email address |
+
+### Response
+
+{
+  "id": "usr_123",
+  "name": "John Doe",
+  "email": "john@example.com",
+  "createdAt": "2025-01-15T10:30:00Z"
+}
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 400 | Invalid request body |
+| 409 | Email already exists |
+```
+
+## 工具
+
+### Generators
+
+| Tool | 用途 |
+|------|---------|
+| swagger-codegen | 生成 client SDKs |
+| openapi-generator | 生成 client／server 代码 |
+| typedoc | 生成 TypeScript 文档 |
+
+### Hosting
+
+| Tool | 类型 |
+|------|------|
+| Swagger UI | 自托管 |
+| Redoc | 自托管 |
+| ReadMe | SaaS |
+| Stoplight | SaaS |
+
+## 规则
+
+| 规则 | 描述 | 优先级 |
+|------|-------------|----------|
+| Document all endpoints | 为每一个公开 endpoint 撰写文档 | Required |
+| Include examples | 纳入 request 与 response 示例 | Required |
+| Document errors | 列出所有可能的 error response | Required |
+| Version sync | 让文档与 API 版本保持同步 | Required |
+| Auth first | 在 endpoint 之前先记录 authentication | Recommended |
+
+## 相关选项
+
+- [Markdown Docs](./markdown-docs.md) - 纯 Markdown 文档
+- [Wiki Style](./wiki-style.md) - Wiki 风格的协作文档
+
+---
+
+## 参考资料
+
+- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
+- [Swagger](https://swagger.io/)
+- [AsyncAPI](https://www.asyncapi.com/)
+
+---
+
+## 授权
+
+本文档以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。
+
+**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-CN/options/documentation/markdown-docs.md

@@ -0,0 +1,150 @@
+---
+source: options/documentation/markdown-docs.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# Markdown 文档
+
+> **语言**: [English](../../../../options/documentation/markdown-docs.md) | 简体中文
+
+**上层标准**: [Documentation Structure](../../core/documentation-structure.md)
+
+---
+
+## 概览
+
+纯 Markdown 文档是一种简单、可移植的项目文档方式。文件直接存储在仓库中，以 Git 进行版本控制，并可在 GitHub 和 GitLab 等平台上原生呈现。
+
+## 最适用于
+
+- 开源项目
+- 托管于 GitHub/GitLab 的项目
+- 以开发者为中心的文档
+- 想要简单、可移植文档的项目
+- 中小型项目
+
+## 文件结构
+
+### 根目录文件
+
+| File | Required | 用途 |
+|------|----------|---------|
+| `README.md` | Yes | 项目概览、快速开始 |
+| `CONTRIBUTING.md` | No | 贡献指南 |
+| `CHANGELOG.md` | No | 版本历史 |
+| `LICENSE` | Yes | 许可证文件 |
+
+### docs/ 文件夹
+
+**位置：** `docs/`
+**命名约定：** lowercase-kebab-case
+
+#### 常见文件
+
+- `getting-started.md`
+- `installation.md`
+- `configuration.md`
+- `api-reference.md`
+- `troubleshooting.md`
+- `faq.md`
+
+#### 子目录
+
+| Directory | 用途 |
+|-----------|---------|
+| `guides/` | 操作指南 |
+| `tutorials/` | 分步教程 |
+| `reference/` | API 与配置参考 |
+| `ADR/` | 架构决策记录 |
+
+## README 模板
+
+```markdown
+# Project Name
+
+Brief description of the project.
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Installation
+
+npm install project-name
+
+## Quick Start
+
+import { something } from 'project-name';
+
+## Documentation
+
+See [docs/](./docs/) for full documentation.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+[MIT](./LICENSE)
+```
+
+## Markdown 最佳实践
+
+- 使用 ATX 样式标题（`#`、`##`、`###`）
+- 在标题前后加入空行
+- 使用指定语言的 fenced code block
+- 将每行控制在 120 字符以内
+- 对重复的 URL 使用 reference-style 链接
+
+## 工具
+
+| Tool | 用途 |
+|------|---------|
+| markdownlint | Lint markdown 文件 |
+| markdown-link-check | 检查失效链接 |
+| docsify | 生成文档网站 |
+| mkdocs | 静态网站生成器 |
+
+## 规则
+
+| 规则 | 说明 | 优先级 |
+|------|-------------|----------|
+| 根目录大写 | 根目录文档使用 UPPERCASE（README、CONTRIBUTING） | Required |
+| docs lowercase-kebab | docs/ 文件使用 lowercase-kebab-case | Required |
+| 相对链接 | 内部链接使用相对路径 | Required |
+| 包含示例 | 为所有功能包含代码示例 | Recommended |
+
+## 与其他方式的比较
+
+| 方面 | 仓库内 Markdown | Wiki | 外部文档网站 |
+|--------|------------------|------|-------------------|
+| 版本控制 | 以 Git 为基础 | 内置 | 视平台而定 |
+| 编辑 | 需要 Git | WYSIWYG／简易 | 不一定 |
+| 离线访问 | 完整 | 有限 | 有限 |
+| 搜索 | GitHub 搜索 | 内置 | 不一定 |
+
+## 相关选项
+
+- [API Docs](./api-docs.md) - API 参考文档
+- [Wiki Style](./wiki-style.md) - Wiki 风格协作文档
+
+---
+
+## 参考资料
+
+- [CommonMark](https://commonmark.org/)
+- [GitHub Flavored Markdown](https://github.github.com/gfm/)
+- [Docsify](https://docsify.js.org/)
+- [MkDocs](https://www.mkdocs.org/)
+
+---
+
+## 许可证
+
+本文档以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。
+
+**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-CN/options/documentation/wiki-style.md

@@ -0,0 +1,131 @@
+---
+source: options/documentation/wiki-style.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# Wiki 风格文档
+
+> **语言**: [English](../../../../options/documentation/wiki-style.md) | 简体中文
+
+**上层标准**: [Documentation Structure](../../core/documentation-structure.md)
+
+---
+
+## 概览
+
+Wiki 风格文档提供一个可协作、易于编辑的知识库。它非常适合内部文档、团队知识分享，以及需要由多位贡献者频繁更新的内容。
+
+## 最适用于
+
+- 大型团队
+- 内部文档
+- 知识库
+- 频繁更新的内容
+- 跨职能团队
+
+## 平台
+
+| 平台 | 厂商 | 最适用于 | 主要特性 |
+|----------|--------|----------|--------------|
+| **Confluence** | Atlassian | 使用 Jira 的企业团队 | 丰富的编辑器、模板、空间、权限 |
+| **Notion** | Notion Labs | 初创公司、灵活需求 | 数据库、模板、嵌套页面、评论 |
+| **GitHub Wiki** | GitHub | 开源、开发者 | 以 Git 为后盾、Markdown、随 repo 免费 |
+| **GitBook** | GitBook | 公开文档 | Git 同步、精美 UI、支持 API docs |
+
+## 结构
+
+### 顶层空间
+
+| 空间 | 内容 |
+|-------|---------|
+| **Engineering** | 架构决策、技术标准、runbook |
+| **Product** | 功能规格、roadmap、用户研究 |
+| **Team** | 新人上手、流程、会议记录 |
+
+### 页面层级
+
+1. 概览／索引页
+2. 分类页
+3. 细节页
+4. 相关链接
+
+## 页面模板
+
+```markdown
+# Page Title
+
+**Last Updated:** YYYY-MM-DD
+**Owner:** @username
+
+## Overview
+
+Brief description of what this page covers.
+
+## Content
+
+Main content here...
+
+## Related Pages
+
+- [Related Page 1](link)
+- [Related Page 2](link)
+
+## Changelog
+
+| Date | Author | Change |
+|------|--------|--------|
+| YYYY-MM-DD | @user | Initial creation |
+```
+
+## 最佳实践
+
+- 为常见的页面类型建立模板
+- 使用一致的命名约定
+- 移动页面时设置重定向
+- 定期进行内容审计
+- 鼓励评论与提问
+- 在页面之间慷慨地建立链接
+
+## 规则
+
+| 规则 | 描述 | 优先级 |
+|------|-------------|----------|
+| 页面归属 | 指派一位负责人维持内容时效性 | Required |
+| 页面日期 | 标注最后更新日期 | Required |
+| 链接相关内容 | 链接到相关页面以提升可发现性 | Recommended |
+| 季度审查 | 审查并更新陈旧内容 | Recommended |
+| 归档过时内容 | 归档而非删除旧内容 | Recommended |
+
+## 与其他做法的比较
+
+| 方面 | Wiki | Repo 中的 Markdown | 外部文档站点 |
+|--------|------|------------------|-------------------|
+| 编辑 | WYSIWYG／容易 | 需要 Git 知识 | 视情况而定 |
+| 版本控制 | 内置 | 以 Git 为基础 | 视平台而定 |
+| 协作 | 优异 | 良好 | 良好 |
+| 搜索 | 内置 | GitHub 搜索 | 视情况而定 |
+| 访问控制 | 细致 | repo 层级 | 视情况而定 |
+| 离线访问 | 有限 | 完整 | 有限 |
+
+## 相关选项
+
+- [API Docs](./api-docs.md) - API 参考文档
+- [Markdown Docs](./markdown-docs.md) - 纯 Markdown 文档
+
+---
+
+## 参考资料
+
+- [Confluence](https://www.atlassian.com/software/confluence)
+- [Notion](https://www.notion.so/)
+- [GitBook](https://www.gitbook.com/)
+
+---
+
+## 许可
+
+本文档依 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。
+
+**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)