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

package/bundled/locales/zh-CN/core/documentation-writing-standards.md

@@ -0,0 +1,495 @@
+---
+source: ../../../core/documentation-writing-standards.md
+source_version: 1.0.1
+translation_version: 1.0.1
+last_synced: 2025-12-30
+status: current
+---
+
+# 文件撰写规范
+
+> [English](../../../core/documentation-writing-standards.md) | **繁体中文**
+
+**版本**: 1.0.1
+**最后更新**: 2025-12-24
+**适用范围**: 所有软体专案（新建、重构、迁移、维护）
+
+---
+
+## 目的
+
+本标准根据专案类型定义文件需求，并提供各类文件的详细撰写指南。
+
+**与其他标准的关系**:
+- 补充 [documentation-structure.md](documentation-structure.md) 所定义的档案组织
+- 本标准聚焦于**内容需求**和**专案类型对照**
+
+---
+
+## 专案类型与文件对照
+
+### 文件需求矩阵
+
+| 文件 | 新建专案 | 重构 | 迁移 | 维护 | 说明 |
+|----------|:-----------:|:-----------:|:---------:|:-----------:|-------------|
+| **README.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 | 专案入口 |
+| **ARCHITECTURE.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | 系统架构 |
+| **API.md** | ⚪ 如适用 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | API 规格 |
+| **DATABASE.md** | ⚪ 如适用 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | 资料库架构 |
+| **DEPLOYMENT.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | 部署指南 |
+| **MIGRATION.md** | ❌ 不需要 | ✅ 必要 | ✅ 必要 | ❌ 不需要 | 迁移计划 |
+| **ADR/** | ⚪ 建议 | ✅ 必要 | ✅ 必要 | ⚪ 如适用 | 架构决策 |
+| **CHANGELOG.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 | 版本历史 |
+| **CONTRIBUTING.md** | ⚪ 建议 | ⚪ 建议 | ⚪ 建议 | ⚪ 如适用 | 贡献指南 |
+
+**图例**: ✅ 必要 | ⚪ 建议/如适用 | ❌ 不需要
+
+---
+
+### 专案类型说明
+
+#### 🆕 新建专案
+
+从零开始建立的软体专案。
+
+**必要文件**:
+- README.md - 专案概述、快速开始
+- ARCHITECTURE.md - 设计架构（开发前规划）
+- DEPLOYMENT.md - 部署流程
+- CHANGELOG.md - 版本历史
+
+**建议文件**:
+- API.md - 如对外提供 API
+- DATABASE.md - 如使用资料库
+- ADR/ - 记录重要技术决策
+
+---
+
+#### 🔄 重构专案
+
+改善既有系统的程序码结构、架构或技术栈，但不改变外部行为。
+
+**必要文件**:
+- README.md - 更新技术栈说明
+- ARCHITECTURE.md - 新旧架构对比
+- API.md - API 变更说明（如适用）
+- DATABASE.md - Schema 变更说明（如适用）
+- DEPLOYMENT.md - 新部署流程
+- MIGRATION.md - 重构迁移计划
+- ADR/ - 记录重构决策
+- CHANGELOG.md - 详细变更记录
+
+**重点**:
+- MIGRATION.md 需包含回滚计划
+- ADR/ 需记录「为何重构」及「为何选择此方案」
+
+---
+
+#### 🚚 迁移专案
+
+将系统从一个环境/平台迁移到另一个（如云端迁移、版本升级）。
+
+**必要文件**:
+- README.md - 新环境说明
+- ARCHITECTURE.md - 新架构图
+- API.md - API 相容性说明
+- DATABASE.md - 资料迁移说明
+- DEPLOYMENT.md - 新环境部署
+- MIGRATION.md - 迁移步骤与验证
+- ADR/ - 迁移决策记录
+- CHANGELOG.md - 迁移变更记录
+
+**重点**:
+- MIGRATION.md 是核心文件
+- 需包含资料迁移验证、回滚计划、集成方通知
+
+---
+
+#### 🔧 维护专案
+
+既有系统的日常维护、Bug 修复、小幅功能增强。
+
+**必要文件**:
+- README.md - 保持更新
+- CHANGELOG.md - 记录每次变更
+
+**建议文件**:
+- 依变更范围更新其他文件
+
+---
+
+## 核心原则
+
+> **文件是程序码的延伸，应与程序码同等重视。好的文件能减少沟通成本、加速新人上手、降低维护风险。**
+
+### 文件金字塔
+
+```
+                    ┌─────────────┐
+                    │   README    │  ← 入口点，快速概览
+                    ├─────────────┤
+                 ┌──┴─────────────┴──┐
+                 │   ARCHITECTURE    │  ← 系统总览
+                 ├───────────────────┤
+              ┌──┴───────────────────┴──┐
+              │  API / DATABASE / DEPLOY │  ← 技术细节
+              ├─────────────────────────┤
+           ┌──┴─────────────────────────┴──┐
+           │    ADR / MIGRATION / CHANGELOG │  ← 变更历史
+           └───────────────────────────────┘
+```
+
+---
+
+## 文件分类与规范
+
+### 1. 架构文件
+
+#### ARCHITECTURE.md
+
+**用途**: 描述系统整体架构、模组划分、技术选型
+
+**必要章节**:
+
+| 章节 | 说明 | 必要性 |
+|---------|-------------|----------|
+| 系统概述 | 目的、范围、主要功能 | 必要 |
+| 架构图 | 使用 Mermaid 或 ASCII Art | 必要 |
+| 模组说明 | 职责、依赖关系 | 必要 |
+| 技术栈 | 框架、语言、资料库版本 | 必要 |
+| 资料流程 | 主要业务流程的资料流向 | 必要 |
+| 部署架构 | 生产环境部署拓扑 | 建议 |
+| 设计决策 | 关键决策的理由（或连结至 ADR） | 建议 |
+
+**范本结构**:
+
+```markdown
+# 系统架构
+
+## 1. 系统概述
+[系统目的与范围]
+
+## 2. 架构图
+[Mermaid 或 ASCII 图]
+
+## 3. 模组说明
+### 3.1 表现层
+### 3.2 业务逻辑层
+### 3.3 资料存取层
+
+## 4. 技术栈
+| 类别 | 技术 | 版本 |
+|----------|------------|---------|
+
+## 5. 资料流程
+[主要业务流程图]
+
+## 6. 部署架构
+[部署拓扑图]
+```
+
+---
+
+### 2. API 文件
+
+#### API.md
+
+**用途**: 记录对外 API 界面
+
+**必要章节**:
+
+| 章节 | 说明 | 必要性 |
+|---------|-------------|----------|
+| API 概述 | 版本、Base URL、认证方式 | 必要 |
+| 认证方式 | Token 取得、过期时间 | 必要 |
+| 端点列表 | 所有 API 端点 | 必要 |
+| 端点规格 | 每个端点的请求/回应格式 | 必要 |
+| 错误码参考 | 错误码与说明 | 必要 |
+| 程序码范例 | 常见语言的范例 | 建议 |
+| 速率限制 | API 呼叫频率限制 | 如适用 |
+
+**端点规格格式**:
+
+```markdown
+### POST /api/v1/resource
+
+描述此端点的功能。
+
+**请求**
+
+| 栏位 | 类型 | 必要 | 说明 |
+|-------|------|----------|-------------|
+| field1 | string | 是 | 说明 |
+| field2 | integer | 否 | 说明 |
+
+**请求范例**
+```json
+{
+  "field1": "value",
+  "field2": 123
+}
+```
+
+**回应**
+
+| 栏位 | 类型 | 说明 |
+|-------|------|-------------|
+| success | boolean | 是否成功 |
+| data | object | 回应资料 |
+
+**回应范例**
+```json
+{
+  "success": true,
+  "data": {}
+}
+```
+
+**错误回应**
+| 代码 | 说明 |
+|------|-------------|
+| 400 | 请求错误 |
+| 401 | 未授权 |
+```
+
+---
+
+### 3. 资料库文件
+
+#### DATABASE.md
+
+**用途**: 记录资料库结构、关联、索引策略
+
+**必要章节**:
+
+| 章节 | 说明 | 必要性 |
+|---------|-------------|----------|
+| 资料库概述 | 类型、版本、连线资讯 | 必要 |
+| ER 图 | 实体关联图 | 必要 |
+| 资料表列表 | 所有资料表及用途 | 必要 |
+| 资料表规格 | 每个资料表的栏位定义 | 必要 |
+| 索引说明 | 索引策略与效能考量 | 必要 |
+| 迁移脚本 | 脚本位置与执行顺序 | 必要 |
+| 备份策略 | 备份频率、保留期限 | 建议 |
+
+**资料表规格格式**:
+
+```markdown
+### 资料表名称
+
+资料表用途说明。
+
+**栏位定义**
+
+| 栏位 | 资料类型 | 可空 | 预设值 | 说明 |
+|--------|-----------|----------|---------|-------------|
+| id | bigint | 否 | IDENTITY | 主键 |
+| name | varchar(100) | 否 | - | 名称栏位 |
+| status | tinyint | 否 | 0 | 状态旗标 |
+
+**索引**
+
+| 索引名称 | 栏位 | 类型 | 说明 |
+|------------|---------|------|-------------|
+| PK_TableName | id | CLUSTERED | 主键 |
+| IX_Status | status, created_at | NONCLUSTERED | 查询最佳化 |
+
+**关联**
+
+| 关联资料表 | 连结栏位 | 关系 |
+|---------------|--------------|--------------|
+| OtherTable | id = other_id | 1:N |
+```
+
+---
+
+### 4. 部署文件
+
+#### DEPLOYMENT.md
+
+**用途**: 记录部署步骤、环境配置、故障排除
+
+**必要章节**:
+
+| 章节 | 说明 | 必要性 |
+|---------|-------------|----------|
+| 环境需求 | 硬体、软体、网路需求 | 必要 |
+| 安装步骤 | 详细安装流程 | 必要 |
+| 配置说明 | 配置档参数说明 | 必要 |
+| 验证方式 | 如何确认部署成功 | 必要 |
+| 故障排除 | 常见问题与解法 | 必要 |
+| 监控设定 | 健康检查、日志位置 | 建议 |
+| 扩展指南 | 如何水平/垂直扩展 | 如适用 |
+
+**配置档说明格式**:
+
+```markdown
+### config.yaml 设定
+
+| 参数 | 预设值 | 说明 | 范例 |
+|-----------|---------|-------------|---------|
+| db.host | localhost | 资料库主机 | `192.168.1.100` |
+| db.port | 5432 | 资料库连接埠 | - |
+| app.timeout | 300 | 请求逾时（秒） | - |
+```
+
+---
+
+### 5. 迁移文件
+
+#### MIGRATION.md
+
+**用途**: 记录迁移计划、向后相容策略、回滚程序
+
+**必要章节**:
+
+| 章节 | 说明 | 必要性 |
+|---------|-------------|----------|
+| 迁移概述 | 目标、范围、时程 | 必要 |
+| 前置准备 | 迁移前需完成的准备 | 必要 |
+| 迁移步骤 | 详细迁移流程 | 必要 |
+| 验证清单 | 迁移后验证项目 | 必要 |
+| 回滚计划 | 失败时的回滚步骤 | 必要 |
+| 向后相容 | API/资料库相容性说明 | 必要 |
+| 集成方通知 | 需通知的外部系统 | 如适用 |
+
+---
+
+### 6. 架构决策记录 (ADR)
+
+#### docs/ADR/NNN-title.md
+
+**用途**: 记录重要的架构决策及其理由
+
+**档案命名**: `NNN-kebab-case-title.md`（例如：`001-use-postgresql.md`）
+
+**必要章节**:
+
+| 章节 | 说明 | 必要性 |
+|---------|-------------|----------|
+| 标题 | 决策名称 | 必要 |
+| 状态 | proposed/accepted/deprecated/superseded | 必要 |
+| 背景 | 为何需要此决策 | 必要 |
+| 决策 | 具体决策内容 | 必要 |
+| 后果 | 决策的影响（正面/负面） | 必要 |
+| 替代方案 | 考虑过的其他选项 | 建议 |
+
+**范本**:
+
+```markdown
+# ADR-001: [决策标题]
+
+## 状态
+已接受
+
+## 背景
+[为何需要此决策...]
+
+## 决策
+[具体决策...]
+
+## 后果
+
+### 正面影响
+- 好处 1
+- 好处 2
+
+### 负面影响
+- 缺点 1
+- 缺点 2
+
+## 替代方案
+1. 方案 A - 因...而拒绝
+2. 方案 B - 因...而拒绝
+```
+
+---
+
+## 品质标准
+
+### 格式要求
+
+| 项目 | 标准 |
+|------|----------|
+| 语言 | 繁体中文 |
+| 编码 | UTF-8 |
+| 行长度 | 建议 ≤ 120 字元 |
+| 图表 | 优先使用 Mermaid，次之 ASCII Art |
+| 连结 | 内部连结使用相对路径 |
+
+### 维护要求
+
+| 项目 | 标准 |
+|------|----------|
+| 同步更新 | 程序码变更时同步更新文件 |
+| 版本标记 | 文件顶部标记版本与更新日期 |
+| 审查纳入 | 程序码审查需包含文件变更 |
+| 定期检视 | 每季检视文件是否过时 |
+
+### 审查清单
+
+提交文件前：
+
+- [ ] 必要章节完整
+- [ ] 无过时或错误资讯
+- [ ] 所有连结有效
+- [ ] 范例可执行/正确
+- [ ] 格式符合标准
+
+---
+
+## 文件位置规范
+
+```
+project-root/
+├── README.md                    # 专案入口文件
+├── CONTRIBUTING.md              # 贡献指南
+├── CHANGELOG.md                 # 变更日志
+├── .standards/ or .claude/      # 开发标准
+│   ├── documentation-writing-standards.md
+│   └── ...
+└── docs/                        # 文件目录
+    ├── INDEX.md                 # 文件索引
+    ├── ARCHITECTURE.md          # 架构文件
+    ├── API.md                   # API 文件
+    ├── DATABASE.md              # 资料库文件
+    ├── DEPLOYMENT.md            # 部署文件
+    ├── MIGRATION.md             # 迁移文件
+    ├── ADR/                     # 架构决策记录
+    │   ├── 001-xxx.md
+    │   └── ...
+    └── DB/                      # 资料库脚本
+```
+
+---
+
+## 工具建议
+
+| 用途 | 工具 |
+|---------|-------|
+| Markdown 编辑 | VS Code + Markdown Preview Enhanced |
+| 图表绘制 | Mermaid / draw.io / PlantUML |
+| API 文件 | OpenAPI (Swagger) / Redoc |
+| ER 图 | dbdiagram.io / DBeaver |
+
+---
+
+## 相关标准
+
+- [Documentation Structure Standard](documentation-structure.md) - 文件结构标准
+- [Changelog Standards](changelog-standards.md) - 变更日志标准
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更内容 |
+|---------|------|---------|
+| 1.0.1 | 2025-12-24 | 新增：相关标准章节 |
+| 1.0.0 | 2025-12-10 | 初版文件撰写标准 |
+
+---
+
+## 授权
+
+本标准以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权发布。

package/bundled/locales/zh-CN/core/error-code-standards.md

@@ -0,0 +1,180 @@
+---
+source: ../../../core/error-code-standards.md
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-01-08
+status: current
+---
+
+> **语言**: [English](../../../core/error-code-standards.md) | [简体中文](../../zh-TW/core/error-code-standards.md) | 简体中文
+
+# 错误码标准
+
+**版本**: 1.0.0
+**最后更新**: 2025-12-30
+**适用范围**: 所有需要统一错误处理的应用程序
+
+---
+
+## 目的
+
+本标准定义统一的错误码管理规范，以提升调试效率、监控能力和用户体验。
+
+---
+
+## 错误码格式
+
+### 标准格式
+
+```
+<前缀>_<类别>_<编号>
+```
+
+| 组成 | 说明 | 示例 |
+|------|------|------|
+| 前缀 | 应用/服务标识 | AUTH, PAY, USR |
+| 类别 | 错误类别 | VAL, SYS, BIZ |
+| 编号 | 唯一数字标识 | 001, 100, 404 |
+
+### 示例
+
+```
+AUTH_VAL_001    → 认证验证错误
+PAY_SYS_503     → 支付系统不可用
+USR_BIZ_100     → 用户业务规则违反
+API_NET_408     → API 网络超时
+```
+
+---
+
+## 错误类别
+
+| 代码 | 类别 | 说明 | HTTP 状态 |
+|-----|------|------|----------|
+| VAL | 验证 | 输入验证失败 | 400 |
+| BIZ | 业务 | 业务规则违反 | 422 |
+| AUTH | 认证 | 安全相关错误 | 401/403 |
+| SYS | 系统 | 内部系统错误 | 500 |
+| NET | 网络 | 通信/连接问题 | 502/503 |
+
+### 验证错误 (VAL)
+
+| 代码范围 | 说明 |
+|---------|------|
+| *_VAL_001-099 | 字段验证 |
+| *_VAL_100-199 | 格式验证 |
+| *_VAL_200-299 | 约束验证 |
+
+### 业务逻辑错误 (BIZ)
+
+| 代码范围 | 说明 |
+|---------|------|
+| *_BIZ_001-099 | 状态违反 |
+| *_BIZ_100-199 | 规则违反 |
+| *_BIZ_200-299 | 限制违反 |
+
+---
+
+## 错误响应格式
+
+### 单个错误
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "AUTH_VAL_001",
+    "message": "邮箱为必填字段",
+    "field": "email",
+    "requestId": "req_abc123"
+  }
+}
+```
+
+### 多个错误
+
+```json
+{
+  "success": false,
+  "errors": [
+    {
+      "code": "AUTH_VAL_001",
+      "message": "邮箱为必填字段",
+      "field": "email"
+    },
+    {
+      "code": "AUTH_VAL_201",
+      "message": "密码至少需要 8 个字符",
+      "field": "password"
+    }
+  ],
+  "requestId": "req_abc123"
+}
+```
+
+---
+
+## 国际化 (i18n)
+
+### 消息键格式
+
+```
+error.<前缀>.<类别>.<编号>
+```
+
+### 翻译文件示例
+
+```yaml
+# zh-CN.yaml
+error:
+  auth:
+    val:
+      001: "邮箱为必填字段"
+      101: "邮箱格式无效"
+    auth:
+      001: "用户名或密码错误"
+      201: "会话已过期"
+```
+
+---
+
+## 快速参考卡
+
+### 代码格式
+
+```
+<前缀>_<类别>_<编号>
+AUTH_VAL_001
+```
+
+### 类别速查
+
+| 代码 | 类别 | HTTP | 用途 |
+|-----|------|------|------|
+| VAL | 验证 | 400 | 输入验证 |
+| BIZ | 业务 | 422 | 业务规则 |
+| AUTH | 认证 | 401/403 | 安全 |
+| SYS | 系统 | 500 | 内部错误 |
+| NET | 网络 | 502/503 | 连接 |
+
+### 检查清单
+
+- [ ] 每个错误有唯一代码
+- [ ] 类别符合错误类型
+- [ ] 用户消息已本地化
+- [ ] HTTP 状态正确
+- [ ] 错误已记录文档
+- [ ] 代码已注册
+
+---
+
+## 相关标准
+
+- [日志标准](logging-standards.md) - 错误日志实践
+- [API 文档标准](api-documentation-standards.md) - 错误响应文档
+
+---
+
+## 许可证
+
+本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。