10 KiB
10 KiB
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 |