universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-CN/core/git-workflow.md

@@ -0,0 +1,193 @@
+---
+source: ../../../core/git-workflow.md
+source_version: 1.2.1
+translation_version: 1.2.1
+last_synced: 2026-01-08
+status: current
+---
+
+> **语言**: [English](../../../core/git-workflow.md) | [简体中文](../../zh-TW/core/git-workflow.md) | 简体中文
+
+# Git 工作流程标准
+
+**版本**: 1.0.0
+**最后更新**: 2025-12-30
+**适用范围**: 所有使用 Git 进行版本控制的项目
+
+---
+
+## 目的
+
+本标准定义 Git 分支策略和工作流程，确保团队协作的一致性和代码质量。
+
+---
+
+## 工作流程选择
+
+### 决策矩阵
+
+| 工作流程 | 团队规模 | 发布频率 | 复杂度 | 最适合 |
+|---------|---------|---------|--------|-------|
+| GitHub Flow | 小型 | 持续 | 低 | SaaS、Web 应用 |
+| Git Flow | 中大型 | 定期 | 高 | 产品软件 |
+| Trunk-Based | 任意 | 持续 | 中 | DevOps 成熟团队 |
+| GitLab Flow | 中型 | 环境驱动 | 中 | 多环境部署 |
+
+---
+
+## GitHub Flow（推荐）
+
+最简单的工作流程，适合持续部署。
+
+```
+main ─────●─────●─────●─────●─────●─────
+           \         /
+feature     ●───●───●
+```
+
+### 分支
+
+| 分支 | 用途 | 生命周期 |
+|-----|------|---------|
+| main | 生产就绪代码 | 永久 |
+| feature/* | 新功能开发 | 临时 |
+
+### 流程
+
+1. 从 main 创建功能分支
+2. 开发并提交变更
+3. 创建 Pull Request
+4. 代码审查
+5. 合并到 main
+6. 自动部署
+
+---
+
+## Git Flow
+
+适合有定期发布周期的项目。
+
+```
+main     ─────●─────────────────●─────
+              │                 │
+develop  ─────●───●───●───●─────●─────
+               \     /   \     /
+feature         ●───●     \   /
+                           \ /
+release                     ●
+```
+
+### 分支
+
+| 分支 | 用途 | 生命周期 |
+|-----|------|---------|
+| main | 生产版本 | 永久 |
+| develop | 开发集成 | 永久 |
+| feature/* | 新功能 | 临时 |
+| release/* | 发布准备 | 临时 |
+| hotfix/* | 紧急修复 | 临时 |
+
+---
+
+## Trunk-Based Development
+
+适合高部署频率的成熟团队。
+
+```
+main ─────●───●───●───●───●───●───●─────
+           \   /   \   /
+short       ●─●     ●─●
+branches
+```
+
+### 特点
+
+- 分支生命周期 < 1 天
+- 频繁集成到 main
+- 依赖功能开关
+- 需要强大的 CI/CD
+
+---
+
+## 分支命名规范
+
+### 格式
+
+```
+<type>/<ticket>-<description>
+```
+
+### 类型
+
+| 类型 | 用途 | 示例 |
+|-----|------|------|
+| feature | 新功能 | feature/PROJ-123-user-login |
+| fix | 错误修复 | fix/PROJ-456-payment-error |
+| hotfix | 紧急修复 | hotfix/PROJ-789-security-patch |
+| release | 发布准备 | release/v2.0.0 |
+| docs | 文档更新 | docs/api-documentation |
+| refactor | 重构 | refactor/auth-module |
+
+---
+
+## Pull Request 规范
+
+### 标题格式
+
+```
+<type>(<scope>): <description>
+```
+
+### 描述模板
+
+```markdown
+## 概述
+简要描述这个 PR 的目的
+
+## 变更内容
+- 变更 1
+- 变更 2
+
+## 测试方案
+- [ ] 单元测试通过
+- [ ] 集成测试通过
+- [ ] 手动测试完成
+
+## 相关 Issue
+Closes #123
+```
+
+---
+
+## 快速参考卡
+
+### 工作流程选择
+
+| 问题 | 答案 | 推荐 |
+|------|------|------|
+| 持续部署？ | 是 | GitHub Flow |
+| 定期发布？ | 是 | Git Flow |
+| 多环境？ | 是 | GitLab Flow |
+| DevOps 成熟？ | 是 | Trunk-Based |
+
+### 分支命名
+
+| 做什么？ | 分支前缀 |
+|---------|---------|
+| 新功能 | feature/ |
+| 修复错误 | fix/ |
+| 紧急修复 | hotfix/ |
+| 发布准备 | release/ |
+
+---
+
+## 相关标准
+
+- [提交消息指南](commit-message-guide.md)
+- [代码审查指南](code-review-guide.md)
+
+---
+
+## 许可证
+
+本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。

package/bundled/locales/zh-CN/core/logging-standards.md

@@ -0,0 +1,174 @@
+---
+source: ../../../core/logging-standards.md
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-01-08
+status: current
+---
+
+> **语言**: [English](../../../core/logging-standards.md) | [简体中文](../../zh-TW/core/logging-standards.md) | 简体中文
+
+# 日志标准
+
+**版本**: 1.0.0
+**最后更新**: 2025-12-30
+**适用范围**: 所有需要日志记录的应用程序
+
+---
+
+## 目的
+
+本标准定义日志记录的最佳实践，确保日志的一致性、结构化和可操作性。
+
+---
+
+## 日志级别
+
+### 标准级别
+
+| 级别 | 代码 | 使用场景 | 生产环境 |
+|------|-----|---------|---------|
+| TRACE | 10 | 非常详细的调试信息 | 关闭 |
+| DEBUG | 20 | 调试诊断信息 | 关闭 |
+| INFO | 30 | 正常操作事件 | 开启 |
+| WARN | 40 | 潜在问题、可恢复错误 | 开启 |
+| ERROR | 50 | 需要关注的错误 | 开启 |
+| FATAL | 60 | 致命故障、程序终止 | 开启 |
+
+### 级别选择指南
+
+| 问题 | 级别 |
+|------|-----|
+| 仅用于调试？ | DEBUG |
+| 正常操作完成？ | INFO |
+| 异常但可接受？ | WARN |
+| 操作失败？ | ERROR |
+| 无法继续？ | FATAL |
+
+---
+
+## 结构化日志
+
+### 必要字段
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00.123Z",
+  "level": "INFO",
+  "message": "用户登录成功",
+  "service": "auth-service",
+  "environment": "production"
+}
+```
+
+### 推荐字段
+
+```json
+{
+  "trace_id": "abc123",
+  "span_id": "def456",
+  "request_id": "req_67890",
+  "user_id": "usr_12345",
+  "duration_ms": 150
+}
+```
+
+### 字段命名规范
+
+- 使用 `snake_case`
+- 跨服务保持一致
+- 按领域添加前缀：`http_`、`db_`、`queue_`
+
+---
+
+## 敏感数据处理
+
+### 绝不记录
+
+- 密码或密钥
+- API 密钥或令牌
+- 信用卡号码
+- 身份证号码
+- 完整的认证令牌
+
+### 脱敏处理
+
+```javascript
+// 错误
+logger.info('登录尝试', { password: userPassword });
+
+// 正确
+logger.info('登录尝试', { password: '***REDACTED***' });
+
+// 正确 - 部分脱敏
+logger.info('卡片处理', { last_four: '4242' });
+```
+
+---
+
+## 错误日志
+
+### 必要字段
+
+```json
+{
+  "level": "ERROR",
+  "message": "数据库连接失败",
+  "error_type": "ConnectionError",
+  "error_message": "连接被拒绝",
+  "error_code": "ECONNREFUSED",
+  "stack": "Error: Connection refused\n    at connect (/app/db.js:45:11)..."
+}
+```
+
+### 错误上下文
+
+始终包含：
+- 尝试执行的操作
+- 相关标识符（user_id、request_id）
+- 输入参数（已脱敏）
+- 重试次数（如适用）
+
+---
+
+## 保留策略
+
+| 日志级别 | 保留期限 |
+|---------|---------|
+| DEBUG | 7 天 |
+| INFO | 30 天 |
+| WARN | 90 天 |
+| ERROR/FATAL | 1 年 |
+
+---
+
+## 快速参考卡
+
+### 必要字段检查清单
+
+- [ ] timestamp（ISO 8601）
+- [ ] level
+- [ ] message
+- [ ] 服务名称
+- [ ] request_id 或 trace_id
+
+### 安全检查清单
+
+- [ ] 无密码或密钥
+- [ ] 无完整令牌
+- [ ] PII 已脱敏
+- [ ] 永不记录信用卡
+- [ ] 已配置保留策略
+
+---
+
+## 相关标准
+
+- [测试标准](testing-standards.md) - 测试日志输出（或使用 `/testing-guide` 技能）
+- [代码审查指南](code-review-guide.md) - 审查日志实践
+
+---
+
+## 许可证
+
+本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。

package/bundled/locales/zh-CN/core/project-structure.md

@@ -0,0 +1,184 @@
+---
+source: ../../../core/project-structure.md
+source_version: 1.0.1
+translation_version: 1.0.1
+last_synced: 2026-01-08
+status: current
+---
+
+> **语言**: [English](../../../core/project-structure.md) | [简体中文](../../zh-TW/core/project-structure.md) | 简体中文
+
+# 项目结构标准
+
+**版本**: 1.0.0
+**最后更新**: 2025-12-30
+**适用范围**: 所有软件项目
+
+---
+
+## 目的
+
+本标准定义项目目录结构的通用规范，确保代码组织的一致性和可维护性。
+
+---
+
+## 通用结构
+
+### 推荐布局
+
+```
+project-root/
+├── src/              # 源代码
+├── tests/            # 测试文件
+├── docs/             # 文档
+├── tools/            # 构建/部署脚本
+│   ├── deployment/
+│   ├── migration/
+│   └── scripts/
+├── examples/         # 使用示例
+├── config/           # 配置文件
+├── .github/          # GitHub 配置
+└── .gitignore
+```
+
+---
+
+## 构建输出（始终 gitignore）
+
+| 目录 | 用途 |
+|------|------|
+| dist/ | 分发输出 |
+| build/ | 编译产物 |
+| out/ | 输出目录 |
+| bin/ | 二进制文件 |
+
+---
+
+## 语言特定结构
+
+### Node.js
+
+```
+project/
+├── src/
+│   ├── index.js
+│   ├── routes/
+│   ├── controllers/
+│   ├── services/
+│   └── models/
+├── tests/
+├── package.json
+└── .gitignore
+```
+
+### Python
+
+```
+project/
+├── src/
+│   └── package_name/
+│       ├── __init__.py
+│       └── main.py
+├── tests/
+├── pyproject.toml
+└── .gitignore
+```
+
+### Go
+
+```
+project/
+├── cmd/
+│   └── appname/
+│       └── main.go
+├── internal/
+├── pkg/
+├── go.mod
+└── .gitignore
+```
+
+### Java/Kotlin
+
+```
+project/
+├── src/
+│   ├── main/
+│   │   └── java/
+│   └── test/
+│       └── java/
+├── build.gradle
+└── .gitignore
+```
+
+---
+
+## Gitignore 模式
+
+### 通用模式
+
+```gitignore
+# 构建输出
+dist/
+build/
+out/
+bin/
+
+# 环境文件
+.env
+.env.*
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# 操作系统
+.DS_Store
+Thumbs.db
+```
+
+### 语言特定
+
+| 语言 | 模式 |
+|------|------|
+| Node.js | node_modules/, *.log |
+| Python | __pycache__/, *.pyc, .venv/ |
+| Go | vendor/ |
+| Java | *.class, target/ |
+| .NET | bin/, obj/ |
+
+---
+
+## 快速参考卡
+
+### 标准目录
+
+| 目录 | 用途 | Gitignore |
+|------|------|-----------|
+| src/ | 源代码 | 否 |
+| tests/ | 测试文件 | 否 |
+| docs/ | 文档 | 否 |
+| dist/ | 构建输出 | 是 |
+| build/ | 编译产物 | 是 |
+| node_modules/ | 依赖 | 是 |
+
+### 检查清单
+
+- [ ] 遵循语言规范
+- [ ] 源代码和测试分离
+- [ ] 构建输出已 gitignore
+- [ ] 配置文件在根目录
+- [ ] 有 README.md
+
+---
+
+## 相关标准
+
+- [文档结构](documentation-structure.md)
+- [Git 工作流程](git-workflow.md)
+
+---
+
+## 许可证
+
+本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。