需求
本文只描述要什么与怎么算达成，用产品 / 用户语言表达。技术方案、数据结构、字段定义见 架构设计。
一、业务现状
| 项 |
状态 |
| 用户 |
内部管理员、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）
- 作为管理员，我打开系统后能看到已配置站点和每个站点的同步状态。
- 我可以选择一个站点并点击同步，系统会拉取钉钉部门和人员数据。
- 我可以打开部门页面，看到树形部门结构，并查看某个部门下的人员。
- 我可以在人员页面输入姓名、手机号或工号，快速定位员工。
- 我可以导出当前站点或当前筛选条件下的人员数据。
- 当钉钉接口失败或密钥错误时，系统会展示失败状态和可读错误信息。
五、验收标准（MVP）
- 站点配置：新增站点后刷新页面仍存在；密钥字段不在列表页明文展示。
- 手动同步：点击同步后生成同步日志；成功后部门和人员数据可查询；失败时保存错误信息。
- 部门浏览：选中站点后展示部门层级；点击部门后右侧人员列表随之过滤。
- 人员搜索筛选：关键词、部门、状态、分页参数可组合使用；结果数量和列表一致。
- 数据导出：JSON 返回 UTF-8 JSON；CSV 可用 Excel 打开且包含表头。
- 静态前端：访问
/ 可打开应用；所有前端请求使用同源 /api/*。
六、范围边界与决策
| 问题 |
决策 |
| 第一版平台 |
本地 / 内网 Web 应用 |
| 是否需要账号 |
MVP 不做登录，后续再评估 |
| 第一版范围 |
站点配置、同步、浏览、搜索、导出 |
| 暂不支持 |
前端框架、云部署、多用户权限、钉钉回调 |
七、待确认 / 风险点
- 钉钉接口配额：需要在同步服务中记录错误和失败位置，避免静默丢数据。
- 部门与用户关系：用户可能属于多个部门，MVP 需保留
dept_id_list 原始 JSON 字段。
- 旧 JSON 迁移：是否需要导入旧 JSON 作为初始数据，待实现同步前确认。
- 密钥存储：MVP 先存 SQLite，后续可评估本机加密或环境变量覆盖。
