## 目标

* 全面清理未用代码、注释废弃块、空文件与无用测试

* 识别并重构重复代码（重复率≥80%）

* 保持现有功能稳定，构建与测试全部通过

* 输出对比报告与文档更新

## 范围

* 后端：`internal/**`、`cmd/**`、`migrations/**`

* 前端管理：`web/admin/**`（Vue/TS/样式与公共组件）

* 通用资源：`docs/**`、脚手架与配置（不更改生产配置）

## 清理策略与工具

* 未用与死代码检测

  * Go：`golangci-lint`（unused、deadcode、revive）、`go vet`

  * TS/Vue：`tsc --noEmit`（类型与未用导出）、`eslint`（no-unused-vars/no-dead-code）

* 注释废弃块识别

  * 规则：Grep 检索注释中出现代码结构（`func|class|export|<template>`），人工确认后删除

* 空文件/无用测试

  * Glob + Read 识别空/仅注释文件；移除未被引用的测试（无匹配运行入口或全跳过）

* 重复代码检测

  * 跨语言：`jscpd`（Vue/TS/Go）或 `dupl`（Go）

  * 阈值：重复度 ≥ 80% 且行数 ≥ 20 行

* 重构原则

  * 后端：抽取到 `internal/pkg/common` 或现有包的工具单元；避免交叉包循环依赖

  * 前端：抽取到 `web/admin/src/components/common` 或 `utils`，保持现有风格与命名

## 执行步骤

1. 基线采集

* 读取项目结构与关键模块，记录当前构建状态（不修改）

* 运行只读分析：语义搜索/正则/Grep，收集疑似未用项、注释废弃块、空文件、重复片段清单

1. 未用代码清理

* 逐文件比对引用关系（Grep/语义搜索），将“未被任何入口引用”标记为候选

* 生成候选清单（含文件路径与符号名），按模块批次删除；每次删除后执行增量构建验证

1. 注释废弃块删除

* 扫描 `//`、`/* */`、`<!-- -->` 中含可编译结构的片段，人工确认后删除

* 对 SFC 中注释的 `<template>/<script>/<style>` 片段严谨处理，避免结构破坏

1. 空文件与无用测试

* 移除 0 字节/仅注释文件；对测试：无法被测试运行器加载、或所有用例被跳过的文件移除

1. 重复代码重构

* 跑相似度分析，生成报告（位置、重复度、建议合并点）

* 抽取公共方法/组件，替换调用方；保持 API 不变，变更点最小化

1. 依赖与引用更新

* 后端：修复 import；前端：修复路径别名与组件引用；保证编译通过

1. 验证与回归

* 构建验证：`go build`、`tsc --noEmit`、前端 `npm run build`（或等价）

* 单/集成测试：运行现有测试；若缺失，补最小冒烟测试（关键模块）

* 功能回归：登录、活动管理、一番赏映射、承诺生成/摘要、开奖与订单查询

## 安全保障

* 分批次清理，每批次后执行构建与核心用例回归

* 只删除“未引用/重复/注释废弃/空”的候选；核心路径（API、路由、策略、DAO、视图）谨慎处理

* 所有变更均记录到临时报告与文档

## 交付物

* 代码对比报告：删除/变更列表（文件路径、符号名、原因）

* 重复代码检测报告：重复片段与重构前后引用图

* 验收文档：构建输出、测试结果、回归清单

* 文档更新：在 `docs/代码清理` 目录建立说明与进度记录

## 本次已执行清理项（2025-12-08）

* 移除抽奖策略注册表冗余（保留接口类型），不影响默认策略与一番赏流程

* 删除 Guild 相关 DAO/Model 生成文件（项目内无引用，运行不受影响）

* 移除管理端 batch\_users 接口与路由挂载（前端无调用）

* 移除管理端 IssueUserToken 路由挂载（前端无调用；代码文件暂保留为未引用状态）

* 构建验证：`go build ./...` 通过；`go test ./...` 存在历史用例失败（外部依赖与软删列缺失），与本次变更无关

## 文档与规范对齐

* 创建：`docs/代码清理/ALIGNMENT_代码清理.md`（范围/边界/不确定点）

* 共识：`docs/代码清理/CONSENSUS_代码清理.md`（验收标准与方案）

* 设计与任务拆分：`docs/代码清理/DESIGN_代码清理.md`、`TASK_代码清理.md`

* 执行与评估：`docs/代码清理/ACCEPTANCE_代码清理.md`、`FINAL_代码清理.md`、`TODO_代码清理.md`

## 后续执行说明

* 获批后：按上述步骤使用只读扫描确定候选清单→分批次提交清理补丁→每批次构建与回归验证→汇总报告与文档更新。