dingding_hrm/AGENTS.md

AGENTS.md

Codex / AI coding agent 的仓库级入口。进入本仓库后，先读本文，再读 docs/00-ai-start-here.md。

项目定位

Dingding HRM 是一个 Go + Gin 本地 Web 应用，用于同步、浏览、搜索和导出钉钉多站点部门与人员数据。

本项目从旧 Python 脚本迁移而来。旧脚本只负责从钉钉 OpenAPI 拉取 JSON 文件；新项目要提供 SQLite 持久化、REST API、原生前端页面和可手动触发的数据同步。

Harness Coding 文档入口

本项目后续编码所需的 harness coding 文档都在 docs/ 目录中。Codex 开始编程时，不需要查找 README.md 或历史分析文件，直接按下面顺序读取 docs/ 即可。

文档	用途
docs/00-ai-start-here.md	AI coding agent 的启动入口、阅读顺序、任务领取规则
docs/01-vision.md	项目目标、用户、产品原则、非目标
docs/02-requirements.md	MVP 需求、用户故事、验收标准
docs/03-tech-stack.md	Go + Gin、SQLite、原生前端等技术选型
docs/04-architecture.md	系统结构、职责边界、数据模型、开发顺序
docs/05-coding-rules.md	写代码前必须遵守的硬规则
docs/06-tasks.md	分阶段任务看板，每轮只领取一个任务
docs/api.md	REST API 合约、错误格式、分页筛选约定
docs/routes.md	原生前端页面路由和模块归属
docs/current-state.md	当前代码现实、可运行命令、下一步任务

必读顺序

每次开始工作前，按顺序读取：

1. AGENTS.md
2. docs/00-ai-start-here.md
3. docs/05-coding-rules.md
4. docs/current-state.md
5. 与当前任务相关的具体文档

如果准备写代码，还必须查看 docs/06-tasks.md，只领取第一个状态为 TODO 且依赖均完成的任务。

技术硬约束

• 后端使用 Go + Gin。
• 数据库使用 SQLite。
• 前端不使用 Vue、React、Svelte、Angular、Element Plus、Vite 等框架或构建链。
• 前端使用原生 HTML/CSS/JavaScript，静态文件由 Gin 托管。
• 钉钉 OpenAPI 只能由后端调用，浏览器端不得直接请求钉钉接口。
• 密钥、token、真实手机号等敏感数据不得写入代码或文档样例。

工作规则

• 需求、API、数据模型或路由变化时，先更新 docs/ 中对应文档。
• 代码实现必须服从 docs/03-tech-stack.md、docs/04-architecture.md 和 docs/api.md。
• 不要引入旧方案中的 Vue / chi 技术栈；最终约束以 docs/ 为准。
• 不要在未确认的情况下引入前端依赖、后台任务库或 ORM。
• 每轮只做一个任务，做完后更新 docs/06-tasks.md 和 docs/current-state.md。

验证

当前尚未初始化代码。初始化后至少维护这些命令：

go test ./...
go build ./...

如果前端只是静态文件，验证应包含：

• Gin 启动后 / 可访问。
• /api/health 返回正常。
• 页面能通过同源 /api/* 请求后端。