dingding_hrm/tasks.md

# Dingding HRM 项目任务拆分

> 项目级任务总表。实际编码时仍按 `docs/00-ai-start-here.md` 和 `docs/06-tasks.md` 的规则：每轮只领取一个可执行任务，完成后更新状态与 `docs/current-state.md`。

## 状态说明

- `TODO`：待开始
- `DOING`：进行中，同一时间最多一个
- `DONE`：已完成并通过验证
- `BLOCKED`：受阻，必须写明原因

## Phase 0 · 项目地基

| ID | 任务 | 依赖 | 交付物 | 验收标准 | 状态 |
| --- | --- | --- | --- | --- | --- |
| T-001 | 初始化 Go module | - | `go.mod`、`go.sum` | `go test ./...` 可执行；模块名明确 | TODO |
| T-002 | 接入 Gin 最小服务 | T-001 | `main.go`、基础 router | `go run .` 启动；`GET /api/health` 返回 `{"ok":true}` | TODO |
| T-003 | 托管原生前端静态文件 | T-002 | `web/index.html`、`web/assets/style.css`、`web/assets/app.js` | 访问 `/` 返回首页；刷新 `/sites`、`/users` 不 404 | TODO |
| T-004 | 建立项目目录结构 | T-002 | `internal/config`、`internal/db`、`internal/handler`、`internal/service` 等目录 | 目录符合 `docs/04-architecture.md` | TODO |
| T-005 | 建立配置加载 | T-004 | 配置模块 | 支持默认端口、数据库路径；不包含真实密钥 | TODO |
| T-006 | 建立统一错误响应 | T-004 | handler 错误工具 | API 错误格式符合 `docs/api.md` | TODO |

## Phase 1 · SQLite 数据层

| ID | 任务 | 依赖 | 交付物 | 验收标准 | 状态 |
| --- | --- | --- | --- | --- | --- |
| T-101 | 接入 SQLite 驱动 | T-005 | DB 初始化代码 | 默认创建或打开 `data/dingding_hrm.db` | TODO |
| T-102 | 实现数据库迁移 | T-101 | migration 代码 | 建表 SQL 覆盖 sites、access_tokens、departments、users、sync_logs | TODO |
| T-103 | 实现站点 repository | T-102 | site repo | 支持增删改查；code 唯一约束生效 | TODO |
| T-104 | 实现 token repository | T-102 | token repo | 支持保存最新 token、查询未过期 token | TODO |
| T-105 | 实现部门 repository | T-102 | department repo | 支持按站点 upsert、清理、查询平铺列表 | TODO |
| T-106 | 实现人员 repository | T-102 | user repo | 支持 upsert、关键词查询、部门筛选、分页计数 | TODO |
| T-107 | 实现同步日志 repository | T-102 | sync log repo | 支持创建 running、更新 success/failed、分页查询 | TODO |
| T-108 | 数据层测试 | T-103 至 T-107 | repository tests | `go test ./...` 通过；覆盖关键约束和分页 | TODO |

## Phase 2 · 站点与基础 API

| ID | 任务 | 依赖 | 交付物 | 验收标准 | 状态 |
| --- | --- | --- | --- | --- | --- |
| T-201 | 实现站点列表 API | T-103 | `GET /api/sites` | 返回 items；不返回 `app_secret` 明文 | TODO |
| T-202 | 实现新增站点 API | T-103 | `POST /api/sites` | 参数校验；新增后可查询 | TODO |
| T-203 | 实现更新站点 API | T-103 | `PUT /api/sites/{site_id}` | 支持更新名称、key、secret；未提交 secret 时保持原值 | TODO |
| T-204 | 实现删除站点 API | T-103 | `DELETE /api/sites/{site_id}` | 删除站点级联清理关联数据 | TODO |
| T-205 | 站点 API 测试 | T-201 至 T-204 | handler tests | 覆盖成功、参数错误、重复 code、删除不存在 | TODO |

## Phase 3 · 钉钉 OpenAPI Client

| ID | 任务 | 依赖 | 交付物 | 验收标准 | 状态 |
| --- | --- | --- | --- | --- | --- |
| T-301 | 定义钉钉 client 接口 | T-004 | `internal/dingtalk` 接口和类型 | 方法覆盖 token、子部门、部门 userid、用户详情 | TODO |
| T-302 | 实现获取 access_token | T-301 | token HTTP 调用 | 支持 app_key/app_secret；错误信息可读 | TODO |
| T-303 | 实现获取子部门列表 | T-302 | department HTTP 调用 | 支持传入 `dept_id`；解析钉钉错误码 | TODO |
| T-304 | 实现获取部门 userid 列表 | T-302 | listid HTTP 调用 | 支持传入 `dept_id`；返回 userid 切片 | TODO |
| T-305 | 实现获取用户详情 | T-302 | user detail HTTP 调用 | 返回核心字段和 raw JSON | TODO |
| T-306 | 钉钉 client 单元测试 | T-302 至 T-305 | httptest tests | 使用 mock server 覆盖成功、钉钉错误、网络错误 | TODO |

## Phase 4 · 同步服务

| ID | 任务 | 依赖 | 交付物 | 验收标准 | 状态 |
| --- | --- | --- | --- | --- | --- |
| T-401 | 实现 token 按需获取服务 | T-104, T-302 | token service | 未过期复用；过期刷新；不向 API 返回 token 明文 | TODO |
| T-402 | 实现部门 BFS 同步 | T-105, T-303, T-401 | department sync | 从 `dept_id=1` 拉完整部门树；支持空子部门 | TODO |
| T-403 | 实现用户详情同步 | T-106, T-304, T-305, T-401 | user sync | 遍历部门 userid 并 upsert 用户详情 | TODO |
| T-404 | 实现全量同步事务边界 | T-402, T-403, T-107 | full sync service | 记录 running/success/failed 日志；失败可定位阶段 | TODO |
| T-405 | 实现同步防并发 | T-404 | sync lock | 同一站点并发同步被拒绝或排队，行为明确 | TODO |
| T-406 | 同步服务测试 | T-404 | service tests | mock 钉钉 client，覆盖成功、失败、部分空数据 | TODO |

## Phase 5 · 查询、导出与统计 API

| ID | 任务 | 依赖 | 交付物 | 验收标准 | 状态 |
| --- | --- | --- | --- | --- | --- |
| T-501 | 实现手动刷新 token API | T-401 | `POST /api/sites/{site_id}/sync/token` | 返回状态和过期时间；不返回 token | TODO |
| T-502 | 实现全量同步 API | T-404 | `POST /api/sites/{site_id}/sync/full` | 成功返回部门数、人员数、log_id | TODO |
| T-503 | 实现部门查询 API | T-105 | `GET /api/sites/{site_id}/departments` | 返回平铺部门列表 | TODO |
| T-504 | 实现人员查询 API | T-106 | `GET /api/sites/{site_id}/users` | 支持 keyword、dept_id、active、page、size | TODO |
| T-505 | 实现人员详情 API | T-106 | `GET /api/sites/{site_id}/users/{userid}` | 返回单人详情；不存在返回 404 | TODO |
| T-506 | 实现 JSON 导出 | T-106 | export service/API | 导出结果服从筛选条件 | TODO |
| T-507 | 实现 CSV 导出 | T-106 | export service/API | UTF-8 CSV，包含表头，Excel 可打开 | TODO |
| T-508 | 实现统计 API | T-105, T-106, T-107 | `GET /api/stats` | 返回每站点部门数、人员数、最近同步状态 | TODO |
| T-509 | 实现同步日志 API | T-107 | `GET /api/sync/logs` | 支持 site_id、status、page、size | TODO |
| T-510 | 查询与导出 API 测试 | T-503 至 T-509 | handler tests | 覆盖分页、筛选、空结果、导出 content-type | TODO |

## Phase 6 · 原生前端基础

| ID | 任务 | 依赖 | 交付物 | 验收标准 | 状态 |
| --- | --- | --- | --- | --- | --- |
| T-601 | 实现页面外壳 | T-003 | `web/index.html`、导航、布局 CSS | `/`、`/sites`、`/departments`、`/users`、`/logs` 可刷新访问 | TODO |
| T-602 | 实现前端 API 封装 | T-601 | `web/assets/api.js` | 统一处理 JSON、错误提示、下载响应 | TODO |
| T-603 | 实现前端状态和 URL 参数工具 | T-601 | `state.js` 或等价模块 | site_id、筛选参数可从 URL 恢复 | TODO |
| T-604 | 建立前端基础样式 | T-601 | `style.css` | 页面清晰、表格和表单可用、移动端不严重错位 | TODO |

## Phase 7 · 原生前端功能页

| ID | 任务 | 依赖 | 交付物 | 验收标准 | 状态 |
| --- | --- | --- | --- | --- | --- |
| T-701 | 实现仪表盘 | T-508, T-602 | dashboard view | 展示站点统计、最近同步状态、同步入口 | TODO |
| T-702 | 实现站点配置页 | T-201 至 T-204, T-602 | sites view | 可新增、编辑、删除站点；secret 不明文展示 | TODO |
| T-703 | 实现部门浏览页 | T-503, T-504, T-603 | departments view | 左侧部门树，右侧部门成员列表 | TODO |
| T-704 | 实现人员搜索页 | T-504, T-506, T-507, T-603 | users view | 支持关键词、部门、状态、分页、导出 | TODO |
| T-705 | 实现同步日志页 | T-509, T-602 | logs view | 支持按站点和状态筛选日志 | TODO |
| T-706 | 接入同步按钮和反馈 | T-502, T-701 | sync UI | 展示同步中、成功、失败状态；失败信息可读 | TODO |

## Phase 8 · 集成验证与边界处理

| ID | 任务 | 依赖 | 交付物 | 验收标准 | 状态 |
| --- | --- | --- | --- | --- | --- |
| T-801 | 完整 API 合约核对 | T-510 | API 对照记录 | 实现路径、参数、响应与 `docs/api.md` 一致 | TODO |
| T-802 | 完整页面路由核对 | T-706 | 路由对照记录 | 实现页面与 `docs/routes.md` 一致 | TODO |
| T-803 | 密钥和敏感信息检查 | T-706 | 检查记录 | 代码、日志、页面列表不泄露 secret/token | TODO |
| T-804 | 空数据和错误状态验收 | T-706 | UI/API 边界处理 | 未配置站点、未同步、钉钉失败都有明确提示 | TODO |
| T-805 | Windows 本地运行验收 | T-706 | 验收记录 | PowerShell 下可 `go run .`、访问页面、运行测试 | TODO |
| T-806 | 文档同步更新 | T-801 至 T-805 | 更新后的 docs | `docs/current-state.md`、`docs/06-tasks.md` 与代码现实一致 | TODO |

## Phase 9 · 打包与交付

| ID | 任务 | 依赖 | 交付物 | 验收标准 | 状态 |
| --- | --- | --- | --- | --- | --- |
| T-901 | 实现生产构建方式 | T-805 | build 命令或脚本 | 可生成 Windows 可执行文件 | TODO |
| T-902 | 确认静态文件打包策略 | T-901 | 嵌入或随包分发方案 | 新目录运行时能访问 `/` 和 `/api/health` | TODO |
| T-903 | 完成交付说明 | T-902 | 更新 `AGENTS.md`、`CLAUDE.md`、`docs/current-state.md` | 新 agent 可快速找到运行、测试、构建方式 | TODO |
| T-904 | MVP 最终验收 | T-903 | 验收记录 | `docs/02-requirements.md` P0 全部通过 | TODO |

## Backlog · 后续迭代

| ID | 任务 | 说明 | 状态 |
| --- | --- | --- | --- |
| B-001 | 定时同步 | 按站点配置周期自动同步 | TODO |
| B-002 | 登录和权限 | 管理员登录、查询用户权限区分 | TODO |
| B-003 | 旧 JSON 数据导入 | 从旧脚本导出的 JSON 初始化 SQLite | TODO |
| B-004 | 部门和人员变更历史 | 记录字段变化、支持对比 | TODO |
| B-005 | 密钥本地加密 | 使用本机安全存储或加密文件降低泄露风险 | TODO |
| B-006 | 操作审计 | 记录站点配置修改、同步触发、导出操作 | TODO |