71 lines
3.0 KiB
Markdown
71 lines
3.0 KiB
Markdown
# 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/*` 请求后端。
|