merge(custom): 兼容环境变量设置默认语言，增加setting页面挪移语言设置位置

2026-08-13 14:45:41 +08:00 · 2025-09-04 11:39:04 +08:00
parent f0d0762272
commit 1d20dcee9d
10 changed files with 20145 additions and 5139 deletions
--- a/docs/api-doc-quick-reference.md
+++ b/docs/api-doc-quick-reference.md
@@ -0,0 +1,176 @@
+# API文档生成快速参考
+
+## 🚀 快速开始
+
+### 1. 代码分析
+```bash
+# 搜索接口定义
+grep_search "api\.trade\.detail" "src/api/*.js"
+
+# 查看页面使用
+read_file "src/subpages/trade/detail.js" 100 200
+
+# 分析字段使用
+grep_search "info\." "src/subpages/trade/detail.js"
+```
+
+### 2. 字段分类
+- **必填字段**: 页面渲染必需，业务逻辑必需
+- **条件必填**: 基于特定条件必须（如自提订单的ziti_info）
+- **可选字段**: 增强功能，统计展示
+
+### 3. 文档生成
+```json
+{
+  "type": "object",
+  "required": ["字段1", "字段2"],
+  "properties": {
+    "字段名": {
+      "type": "数据类型",
+      "description": "中文描述",
+      "example": "示例值"
+    }
+  }
+}
+```
+
+## 📋 必填字段判断标准
+
+### 页面渲染必需
+- 订单状态显示：`order_status`
+- 商品列表：`items` 数组
+- 收货地址：`receiver_*` 系列
+- 价格计算：`total_fee`, `item_fee_new`
+
+### 业务逻辑必需
+- 支付处理：`pay_type`, `pay_channel`
+- 配送状态：`delivery_status`, `receipt_type`
+- 售后处理：`can_apply_aftersales`
+
+### 用户体验必需
+- 订单跟踪：`auto_cancel_seconds`
+- 操作权限：`can_apply_cancel`
+
+## 🔧 常用工具命令
+
+### 搜索工具
+```bash
+# 语义搜索
+codebase_search "订单详情接口"
+
+# 精确搜索
+grep_search "order_id"
+
+# 文件搜索
+file_search "trade.js"
+```
+
+### 文档工具
+```bash
+# 创建文档
+edit_file "新接口文档.json"
+
+# 更新文档
+search_replace "旧内容" "新内容"
+
+# 删除文档
+delete_file "过时文档.json"
+```
+
+## 📝 文档结构模板
+
+### 基础结构
+```json
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "接口名称",
+    "description": "基于项目代码分析的实际字段使用情况",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/api/path": {
+      "get": {
+        "summary": "接口摘要",
+        "description": "详细描述",
+        "operationId": "操作ID",
+        "tags": ["标签"],
+        "parameters": [],
+        "responses": {},
+        "security": [{"BearerAuth": []}]
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      }
+    }
+  }
+}
+```
+
+### 字段定义
+```json
+{
+  "type": "object",
+  "required": ["必填字段"],
+  "properties": {
+    "字段名": {
+      "type": "string|integer|number|boolean|array|object",
+      "description": "字段描述",
+      "example": "示例值",
+      "enum": ["值1", "值2"]
+    }
+  }
+}
+```
+
+## ✅ 质量检查清单
+
+### 完整性
+- [ ] 所有必填字段已标记
+- [ ] 字段描述完整准确
+- [ ] 示例值合理有效
+- [ ] 数据类型正确
+
+### 一致性
+- [ ] 字段命名与代码一致
+- [ ] 数据类型与代码一致
+- [ ] 枚举值与代码一致
+
+### 可用性
+- [ ] 可以直接导入Apifox
+- [ ] 字段映射关系清晰
+- [ ] 错误响应定义完整
+
+## 🚨 常见问题
+
+### 字段缺失
+- 检查代码中是否遗漏
+- 确认字段是否真的不需要
+
+### 数据类型错误
+- 查看代码中的实际类型
+- 确认API响应的真实格式
+
+### 必填字段判断
+- 分析页面使用情况
+- 确认缺失是否导致错误
+
+## 📚 相关文档
+
+- [完整规则文档](./api-documentation-rules.md)
+- [订单详情接口文档](../订单详情接口文档-Apifox.json)
+- [订单详情必填字段说明](../订单详情接口必填字段说明.md)
+
+## 🎯 最佳实践
+
+1. **先分析代码，再写文档**
+2. **必填字段要谨慎判断**
+3. **使用中文描述，便于理解**
+4. **定期更新，保持同步**
+5. **测试验证，确保准确**