完善 API 文档生成规范：统一路由注册和 OpenAPI 文档自动生成

主要改进：
1. 新增 docs/api-documentation-guide.md 详细文档指南
2. 在 AGENTS.md 中添加路由注册规范章节
3. 更新 README.md 文档目录结构

路由注册改进：
- 统一使用 Register() 函数注册路由并自动生成文档
- 所有接口必须指定 RouteSpec（Summary, Tags, Input, Output, Auth）
- 修复 docs.go 和 gendocs/main.go 使用 RegisterRoutesWithDoc 统一注册

DTO 规范更新：
- shop_dto.go 和 shop_account_dto.go 补充完整的 description 标签
- 所有枚举字段必须列出可能值和中文说明

文档生成优化：
- admin-openapi.yaml 自动生成更新
- 健康检查和任务管理接口加入文档
- H5 认证接口完整文档化

规范文档管理：
- 添加规范文档管理流程说明
- 详细文档放在 docs/ 目录
- AGENTS.md 只保留核心规则和引导链接

AGENTS.md

@@ -263,6 +263,33 @@ func (ModelName) TableName() string {
 - ✅ 时间字段使用 `*time.Time`（可空）或 `time.Time`（必填）
 - ✅ JSONB 字段需要实现 `driver.Valuer` 和 `sql.Scanner` 接口
 
+## API 路由注册规范
+
+**核心要求：所有 HTTP 接口必须使用统一的 `Register()` 函数注册，以自动加入 OpenAPI 文档生成。**
+
+```go
+// ✅ 正确
+Register(router, doc, basePath, "POST", "/shops", handler.Create, RouteSpec{
+    Summary: "创建店铺",
+    Tags:    []string{"店铺管理"},
+    Input:   new(model.CreateShopRequest),
+    Output:  new(model.ShopResponse),
+    Auth:    true,
+})
+
+// ❌ 错误：直接注册不会生成文档
+router.Post("/shops", handler.Create)
+```
+
+**RouteSpec 必填项：**
+- `Summary` - 操作说明（中文，简短）
+- `Tags` - 分类标签（用于文档分组）
+- `Input` - 请求 DTO（`nil` 表示无参数）
+- `Output` - 响应 DTO（`nil` 表示无返回）
+- `Auth` - 是否需要认证
+
+**完整指南**: 参见 [`docs/api-documentation-guide.md`](docs/api-documentation-guide.md)
+
 ## 数据库设计
 
 **核心规则:**
@@ -520,4 +547,89 @@ make migrate-up
 8. ✅ 文档更新计划
 9. ✅ 中文优先
 
-**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`
+**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`
+
+## 规范文档管理
+
+### 添加新规范的流程
+
+当你需要为项目添加新的开发规范时，必须遵循以下流程：
+
+#### 1. 创建详细规范文档
+
+在 `docs/` 目录下创建详细的规范文档（Markdown 格式）：
+
+```
+docs/
+├── api-documentation-guide.md    # API 文档生成规范
+├── code-review-checklist.md      # 代码审查清单
+├── testing-guide.md               # 测试规范
+└── ...
+```
+
+**文档内容要求**：
+- ✅ 包含完整的规范说明、示例代码、常见问题
+- ✅ 使用中文编写，代码示例使用英文
+- ✅ 提供正确示例（✅）和错误示例（❌）的对比
+- ✅ 包含故障排查和调试指南
+
+#### 2. 在 AGENTS.md 中添加简短引导
+
+在 `AGENTS.md` 的相关章节中添加**简短**的规范说明 + 引导链接：
+
+```markdown
+## XXX 规范
+
+**核心要求：一句话说明最重要的规则。**
+
+```go
+// ✅ 正确示例（3-5 行）
+...
+
+// ❌ 错误示例（3-5 行）
+...
+```
+
+**关键要点**：
+- 规则 1
+- 规则 2
+- 规则 3
+
+**完整指南**: 参见 [`docs/xxx-guide.md`](docs/xxx-guide.md)
+```
+
+**注意**：
+- ⚠️ AGENTS.md 中的说明不超过 20 行
+- ⚠️ 只保留最核心的规则和示例
+- ⚠️ 必须包含引导链接到详细文档
+
+#### 3. 在 README.md 中添加文档链接
+
+在 `README.md` 的"## 文档"章节中添加链接：
+
+```markdown
+## 文档
+
+### 开发规范
+
+- **[API 文档生成规范](docs/api-documentation-guide.md)**：路由注册规范、DTO 规范、OpenAPI 文档生成流程
+- **[XXX 规范](docs/xxx-guide.md)**：简短的一句话说明
+```
+
+**分类规则**：
+- 开发规范：代码规范、API 规范、测试规范
+- 功能指南：功能使用指南、配置指南
+- 架构设计：设计文档、技术选型
+
+### 规范文档的维护
+
+**更新规范时**：
+1. 优先更新 `docs/` 下的详细文档
+2. 如果核心规则变化，同步更新 AGENTS.md 中的简短说明
+3. 保持 AGENTS.md 简洁，避免冗余
+
+**删除规范时**：
+1. 删除 `docs/` 下的详细文档
+2. 删除 AGENTS.md 中的相关章节
+3. 删除 README.md 中的链接
+4. 说明删除原因（在 commit message 中）