# 需求

> 本文只描述要什么与怎么算达成，用产品 / 用户语言表达。技术方案、数据结构、字段定义见 [架构设计](04-architecture.md)。

## 一、业务现状

| 项 | 状态 |
| --- | --- |
| 用户 | 内部管理员、HR / 行政人员需要查看多站点钉钉组织和人员数据 |
| 数据 | 旧 Python 脚本可从钉钉 OpenAPI 拉取部门、部门用户 ID、用户详情，并保存为 JSON |
| 现有系统 | 当前仓库尚未有应用代码；旧项目位于 `D:\PythonP\snippets\DingtalkHRM` |
| 约束 | 钉钉 OpenAPI 有 CORS 和密钥安全限制，必须由后端代理调用 |

## 二、用户角色

- 管理员：配置站点、维护 app_key / app_secret、触发同步、查看同步日志。
- 查询用户：浏览部门树、搜索人员、导出当前人员数据。
- 未登录用户：MVP 暂不做登录，默认运行在本地或受信内网。

## 三、功能清单

### 第一版 MVP（最小闭环）

| 功能 | 用户能做什么 | 优先级 |
| --- | --- | --- |
| 站点配置 | 新增、修改、删除梅州 / 东莞 / 合肥等站点配置 | P0 |
| 手动全量同步 | 对指定站点拉取部门和人员详情并写入 SQLite | P0 |
| 部门浏览 | 选择站点后查看部门树，点击部门查看成员 | P0 |
| 人员搜索筛选 | 按姓名、手机号、工号关键词搜索，按部门和状态筛选 | P0 |
| 分页列表 | 以表格分页展示人员核心字段 | P0 |
| 数据导出 | 导出当前站点或筛选结果为 JSON / CSV | P0 |
| 同步日志 | 查看最近同步时间、状态和错误信息 | P0 |

### 后续迭代

| 功能 | 描述 | 阶段 |
| --- | --- | --- |
| 定时同步 | 按配置周期自动同步站点数据 | V2 |
| 登录权限 | 增加管理员账号和访问控制 | V2 |
| 增量同步 | 优先同步变更数据，减少 OpenAPI 调用 | V3 |
| 变更历史 | 记录部门和人员字段变化 | V3 |

## 四、核心用户故事（MVP）

1. 作为管理员，我打开系统后能看到已配置站点和每个站点的同步状态。
2. 我可以选择一个站点并点击同步，系统会拉取钉钉部门和人员数据。
3. 我可以打开部门页面，看到树形部门结构，并查看某个部门下的人员。
4. 我可以在人员页面输入姓名、手机号或工号，快速定位员工。
5. 我可以导出当前站点或当前筛选条件下的人员数据。
6. 当钉钉接口失败或密钥错误时，系统会展示失败状态和可读错误信息。

## 五、验收标准（MVP）

- 站点配置：新增站点后刷新页面仍存在；密钥字段不在列表页明文展示。
- 手动同步：点击同步后生成同步日志；成功后部门和人员数据可查询；失败时保存错误信息。
- 部门浏览：选中站点后展示部门层级；点击部门后右侧人员列表随之过滤。
- 人员搜索筛选：关键词、部门、状态、分页参数可组合使用；结果数量和列表一致。
- 数据导出：JSON 返回 UTF-8 JSON；CSV 可用 Excel 打开且包含表头。
- 静态前端：访问 `/` 可打开应用；所有前端请求使用同源 `/api/*`。

## 六、范围边界与决策

| 问题 | 决策 |
| --- | --- |
| 第一版平台 | 本地 / 内网 Web 应用 |
| 是否需要账号 | MVP 不做登录，后续再评估 |
| 第一版范围 | 站点配置、同步、浏览、搜索、导出 |
| 暂不支持 | 前端框架、云部署、多用户权限、钉钉回调 |

## 七、待确认 / 风险点

- 钉钉接口配额：需要在同步服务中记录错误和失败位置，避免静默丢数据。
- 部门与用户关系：用户可能属于多个部门，MVP 需保留 `dept_id_list` 原始 JSON 字段。
- 旧 JSON 迁移：是否需要导入旧 JSON 作为初始数据，待实现同步前确认。
- 密钥存储：MVP 先存 SQLite，后续可评估本机加密或环境变量覆盖。