bindbox-game/docs/开发规范/TASK_开发规范.md

TASK: 开发规范文档撰写任务拆解

基于 DESIGN_开发规范.md，现将最终文档的撰写工作拆解为以下原子任务。这些任务将按顺序执行，以确保最终交付物的完整性和准确性。

任务依赖图

graph TD
    subgraph 撰写最终文档
        T1[任务1: 撰写概述章节] --\u003e T2
        T2[任务2: 撰写目录与文件结构章节] --\u003e T3
        T3[任务3: 撰写命名规范章节] --\u003e T4
        T4[任务4: 撰写 API Handler 规范章节] --\u003e T5
        T5[任务5: 撰写 DTO 规范章节] --\u003e T6
        T6[任务6: 撰写错误处理规范章节] --\u003e T7
        T7[任务7: 撰写日志记录规范章节] --\u003e T8
        T8[任务8: 撰写注释与文档(Swagger)章节] --\u003e T9
        T9[任务9: 整合所有章节并最终审查]
    end

原子任务清单

任务 1: 撰写“概述”章节

• 输入契约: DESIGN_开发规范.md 中关于“概述”的描述。
• 输出契约: 完成 docs/开发规范.md 中“概述”章节的文本内容。
• 实现约束: 语言简洁，清晰传达规范的目的和原则。

任务 2: 撰写“目录与文件结构”章节

• 输入契约: DESIGN_开发规范.md 中关于目录结构的规则，以及对 internal/api/admin 目录的分析结果。
• 输出契约: 完成 docs/开发规范.md 中“目录与文件结构”章节的文本和示例代码。
• 实现约束: 必须提供清晰的目录树示例。

任务 3: 撰写“命名规范”章节

• 输入契约: DESIGN_开发规范.md 中关于命名规范的规则。
• 输出契约: 完成 docs/开发规范.md 中“命名规范”章节的文本内容。
• 实现约束: 规则需明确，覆盖文件、结构体、函数等不同场景。

任务 4: 撰写“API Handler 规范”章节

• 输入契约: DESIGN_开发规范.md 中关于 Handler 的详细设计，以及 admin 模块的源码作为示例。
• 输出契约: 完成 docs/开发规范.md 中“API Handler 规范”章节的文本和代码示例。
• 实现约束: 代码示例需完整展示 Handler 的标准写法。

任务 5: 撰写“数据传输对象 (DTO) 规范”章节

• 输入契约: DESIGN_开发规范.md 中关于 DTO 的设计，以及 admin 模块的源码作为示例。
• 输出契约: 完成 docs/开发规范.md 中“DTO 规范”章节的文本和代码示例。
• 实现约束: 需重点说明 json 和 binding tag 的用法。

任务 6: 撰写“错误处理规范”章节

• 输入契约: DESIGN_开发规范.md 中关于错误处理的设计，以及 admin 模块的源码作为示例。
• 输出契约: 完成 docs/开发规范.md 中“错误处理规范”章节的文本和代码示例。
• 实现约束: 需清晰解释 ctx.AbortWithError 和 core.Error 的使用方法。

任务 7: 撰写“日志记录规范”章节

• 输入契约: DESIGN_开发规范.md 中关于日志记录的设计。
• 输出契约: 完成 docs/开发规范.md 中“日志记录规范”章节的文本内容。
• 实现约束: 虽然示例不明显，但需根据项目架构（handler 中注入了 logger）推荐标准实践。

任务 8: 撰写“注释与文档(Swagger)”章节

• 输入契约: DESIGN_开发规范.md 中关于 Swagger 的设计，以及 admin 模块的源码作为示例。
• 输出契约: 完成 docs/开发规范.md 中“注释与文档(Swagger)”章节的文本和代码示例。
• 实现约束: 需提供一个完整的 Swagger 注解块作为模板。

任务 9: 整合所有章节并最终审查

• 输入契约: 已完成的所有章节内容。
• 输出契约: 一份格式统一、内容完整、无错误的 docs/开发规范.md 文档。
• 实现约束: 检查文档的流畅性、一致性和准确性。