# 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`。

## 验证

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

```powershell
go test ./...
go build ./...
```

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

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