# wxdgaming.taskflow **Repository Path**: wxd-gaming/wxdgaming.taskflow ## Basic Information - **Project Name**: wxdgaming.taskflow - **Description**: 工单系统 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-16 - **Last Updated**: 2026-10-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # TaskFlow · 飞书内嵌任务流 > 一套给小团队用的**类禅道工单系统**:需求 / Bug / 任务从提单到验收全链路留痕,直接嵌在飞书里用,不需要再注册一套账号。 > Spring Boot 3.2 + Java 21 + H2 文件库 + 无构建原生 JS 前端,**单进程一条命令启动**,适合内网自部署。 ![工单看板](docs/images/01-board.png) --- ## 目录 - [为什么做这个](#为什么做这个) - [界面速览](#界面速览) - [核心概念与状态机](#核心概念与状态机) - [技术栈与代码结构](#技术栈与代码结构) - [快速开始](#快速开始) - [配置项](#配置项) - [测试](#测试) - [API 概览](#api-概览) - [文档地图](#文档地图) - [已知边界与安全提示](#已知边界与安全提示) --- ## 为什么做这个 团队用表格 + 群聊派活,通常三个月后会遇到同一批问题:谁在做什么没人说得清、需求提完就沉了、验收没有凭据、催办靠人肉。TaskFlow 针对这些点做了取舍: | 场景 | 做法 | | --- | --- | | 一条需求要多个职能配合 | 一张工单自动展开**策划 / 美术 / 前端 / 后端 / 测试**五条路线,各组独立推进,互不阻塞 | | 不想再管一套账号 | 飞书端内免登进入,成员身份取自飞书;新用户注册后由管理员审核放行 | | 派单只认"看得见的人" | 执行人是"看得见这张单即可标记"的对接标记,组长缺位时组员可自行认领、管理员可兜底代派 | | 数据边界 | 项目 = 归属 + 可见范围,成员只看到被授权的项目和自己参与过的工单(Tier A/B 两级可见性) | | 我的活在哪 | 侧栏**待办五桶**:待我把关 / 待我干活 / 我提的待跟进 / @我待回应 / 已逾期 | | 版本进度汇报 | 首屏总览报表(KPI + 状态分布 + 版本完成度)+ 一键导出 25 列 CSV(UTF-8 BOM,防公式注入) | | 事后的追责与复盘 | 工单内操作日志 + 请求级审计日志(PII 落库前脱敏),评论与附件只增不改不删 | ## 界面速览 **总览报表**:KPI 指标卡、状态分布(圆图 / 柱状图)、版本完成度与发布倒计时。 ![总览报表](docs/images/02-report.png) **我的待办**:五桶分类视图,逾期、待我认领、待我审核在卡片上直接标出。 ![我的待办](docs/images/03-todo.png) **工单详情**:五条派遣路线独立推进(待派遣 / 待处理 / 进行中 / 已完成 / 无需介入),Bug 单带严重度与复现三要素,右侧是评论与操作日志。 ![工单详情](docs/images/04-detail.png) **提单表单**:所属项目、分组、类型、优先级、版本归尾、截止日期、工时预估、标签、附件。 ![新建工单](docs/images/08-form.png) **项目与权限**:项目 = 归属与可见边界,支持授权成员、项目内组长覆盖、待归类工单批量归类。 ![项目管理](docs/images/05-project.png) **版本排期 / 分组管理 / 成员矩阵 / 注册审核**: ![版本管理](docs/images/06-version.png) ![分组管理](docs/images/07-groups.png) ![分组成员管理](docs/images/10-members.png) ![注册用户审核](docs/images/09-review.png) > 以上截图均为**虚构演示数据**(张三 / 李四 / 王五…),不含任何真实成员信息。 ## 核心概念与状态机 工单主链九态,唯一真源是 `RequirementStatus.allowedTransitions`(新增流转必须先改枚举再改 Service): ```mermaid stateDiagram-v2 [*] --> DRAFT: 提单 DRAFT --> PENDING_REVIEW: 提交审核 PENDING_REVIEW --> APPROVED: 管理员通过 PENDING_REVIEW --> REJECTED: 驳回 REJECTED --> PENDING_REVIEW: 修改后重提 APPROVED --> ASSIGNED: 路线派单 ASSIGNED --> IN_PROGRESS: 执行人开工 ASSIGNED --> PENDING_ACCEPTANCE: 全组无需介入 IN_PROGRESS --> PENDING_ACCEPTANCE: 全部路线完成 PENDING_ACCEPTANCE --> IN_PROGRESS: 验收不通过(返工) PENDING_ACCEPTANCE --> ACCEPTED: 验收通过 ACCEPTED --> CLOSED: 归档 CLOSED --> [*] note right of CLOSED: 除 CLOSED 外任意状态可直接关闭
重开只走 RequirementService.reopen,回到关闭前状态 ``` | 状态 | 界面文案 | Bug 单文案 | | --- | --- | --- | | `DRAFT` | 草稿 | 草稿 | | `PENDING_REVIEW` | 待审核 | 待审核 | | `REJECTED` | 审核驳回 | 驳回确认 | | `APPROVED` | 已审核 | 已审核 | | `ASSIGNED` | 已派单 | 已派单 | | `IN_PROGRESS` | 进行中 | 进行中 | | `PENDING_ACCEPTANCE` | 待验收 | 待验证 | | `ACCEPTED` | 已验收 | 已验证 | | `CLOSED` | 已关闭 | 已关闭 | 其它维度:类型 `REQUIREMENT 需求 / BUG / TASK 任务`,优先级 `P0 紧急 … P3 低`,路线状态 `NONE 无需介入 / PENDING 待处理 / IN_PROGRESS / DONE`,Bug 严重度 `S1 致命 … S5 提示`。 ## 技术栈与代码结构 | 层 | 选型 | | --- | --- | | 后端 | Spring Boot 3.2.5 / Java 21 / Spring Data JPA / Lombok | | 存储 | H2 **文件库**(`./data/taskflow.mv.db`,`MODE=MySQL`),无外部数据库依赖 | | 前端 | `src/main/resources/static/` 下**无构建**原生 JS 单页(`index.html` + `app.js` + `style.css`),不引第三方库与 CDN | | 身份 | 飞书开放平台免登 + 浏览器扫码 OAuth,服务端签发 `TF_SESSION` 会话 Cookie | | 通知 | 飞书消息卡片,12 个工单节点 + 每日 09:30 定时催办 | | 运维 | H2 定时备份(每小时留 24 份、每日留 15 份)、审计日志脱敏 | ``` src/main/java/com/taskflow/ ├── config 9 个 飞书客户端 / 会话门禁 / 数据初始化 / 备份 / 催办 / 审计 ├── controller 14 个 薄 REST 层(写操作统一注入 @CurrentOperator) ├── service 19 个 业务编排,写操作 @Transactional ├── entity 27 个 18 个 JPA 实体 + 9 个枚举(枚举自带中文 label) ├── repository 18 个 Spring Data 派生查询 └── dto 1 个 仅 FeishuUser record(实体直接作为 API 载荷是有意设计) ``` 约 **89 个主 Java 文件 / 1.1 万行**,`app.js` 约 4 000 行。所有状态变更都会落一条 `OperationLog`,与业务写操作同事务。 ## 快速开始 前置:**JDK 21**(`pom.xml` 要求 21,同机有 JDK 8/25 也不要混用)。Maven 3.9.x 未在 PATH 时,启动脚本会回落到仓库内置的 `tools/apache-maven-3.9.6`,再不行自动下载。 ```bash git clone https://github.com/wxd-gaming/wxd-gaming-taskflow.git cd wxd-gaming-taskflow # Windows:双击或执行 start.cmd(内部调用 start.ps1) # 手工启动: mvn spring-boot:run ``` **必须在仓库根目录启动**:H2 走相对路径 `./data/taskflow`,在别的目录启动会分裂出第二个数据库,表现为数据"凭空消失"。 启动后监听 `8080`。接入飞书时,访问地址必须与飞书开放平台「安全设置 → 重定向 URL」登记的**完全一致**(内网自部署通常是 `http://<你的内网IP>:8080`),用 `localhost` 或别的 IP 打开会在换取授权码时直接失败。 ### 不接飞书,先本地体验 ```powershell $env:FEISHU_ENABLED="false" # 关闭免登门禁 mvn spring-boot:run ``` 此时身份来自请求头 `X-Operator-Id` / `X-Operator-Name`,前端读 `localStorage.tf_user`(默认 `local / 本地用户`)。浏览器控制台执行下面这句即可切换成管理员视角,再配合 `POST /api/requirements` 等接口自行灌数据: ```js localStorage.setItem('tf_user', JSON.stringify({ id: 'demo-admin', name: '张三' })); location.reload(); ``` 首个注册用户恒为 `APPROVED` 并可初始化管理密码(`POST /api/security/init`,密码 ≥ 8 位),此后敏感操作需要 `X-Admin-Token`(内存态、30 分钟滑动过期,重启即失效)。 ### 生产打包 ```bash mvn -DskipTests package # 产出 target/taskflow-1.0.0.jar java -jar target/taskflow-1.0.0.jar ``` ## 配置项 全部在 `src/main/resources/application.yml`,可用环境变量或**不入库的** `./config/application.yml`(已 gitignore)覆盖。 | 配置 | 默认值 | 说明 | | --- | --- | --- | | `server.port` | `8080` | 端口 | | `spring.datasource.url` | `jdbc:h2:file:./data/taskflow` | 相对启动目录;故意不开 `AUTO_SERVER`,避免局域网直连库文件绕过业务权限 | | `feishu.enabled` | `${FEISHU_ENABLED:true}` | 关闭后走请求头身份,仅本地/测试 | | `feishu.app-id` | `${FEISHU_APP_ID:}`(占位符) | 自建应用 App ID,用环境变量或 `./config/application.yml` 覆盖 | | `feishu.app-secret` | `${FEISHU_APP_SECRET:}` | **只从环境变量注入,yml 内留空** | | `feishu.allowed-redirect-hosts` | `127.0.0.1:8080` | 回调 Host 白名单,防 Host 伪造;接飞书时须改成开放平台登记的地址 | | `spring.h2.console.enabled` | `false` | 永久关闭(库账号 `sa` 无密码) | | `taskflow.attachment.dir` / `max-total-mb` | `./data/attachments` / `1024` | 附件目录与全库附件总量上限 | | `taskflow.backup.*` | `enabled=true`,`hourly-keep=24`,`daily-keep=15` | H2 `BACKUP TO` 定时备份 | | `taskflow.notify.web-url` | `http://127.0.0.1:8080` | 通知卡片跳转地址,催办场景必须配置成收件端可达的地址 | | `taskflow.export.max-rows` | `20000` | 单次 CSV 导出行数上限 | | `taskflow.reminder.*` | `cron=0 30 9 * * *`,阈值 3 天 | 到期提醒 / 逾期升级 / 滞留催办,去重幂等 | | `spring.servlet.multipart.max-file-size` | `50MB` | 单个附件上限(请求上限 60MB) | ## 测试 ```bash mvn test ``` 5 个测试类、98 个用例,全部跑**独立内存 H2**(`create-drop`)并置 `feishu.enabled=false`,不碰 `./data`: | 测试类 | 覆盖 | | --- | --- | | `TaskFlowApiIntegrationTest` | 业务全链路(MockMvc,按 `@Order` 分段):权限矩阵、状态流转、派单、Bug 闭环、评论附件、CSV 导出、待办、催办、报表、父子单、备份 | | `SessionSecurityIntegrationTest` | 会话门禁:401、会话身份覆盖请求头、登出吊销、伪造令牌与 state 重放、H2 控制台禁用 | | `PathConfusionSecurityIntegrationTest` | 真实 Tomcat `RANDOM_PORT` 直发 `%XX` / `;` / `.` / `//` 畸形路径,钉死状态码 | | `EnumCheckConstraintSyncTest` / `LegacyTrackMigrationTest` | 枚举 CHECK 白名单同步、历史路线数据迁移 | ## API 概览 14 个 `@RestController`、85 个端点,前缀 `/api`。写操作需身份头/会话,标注项另需 `X-Admin-Token`。 | 分组 | 端点数 | 说明 | | --- | --- | --- | | `/api/requirements` | 29 | 增删改查、分页 `/page`、`/stats`、`/flame`、`/export`、状态流转、路线派单、归属与计划、批量归类 | | `/api/users` | 11 | 成员名单、注册审核、停用启用、项目可见范围、个人偏好 | | `/api/projects` | 10 | 项目与成员授权、项目内组长覆盖(写操作全需令牌) | | `/api/auth` | 6 | 飞书免登、浏览器扫码 authorize / status / callback / logout、前端配置探测 | | `/api/versions` `/api/groups` `/api/group-members` | 5 / 4 / 4 | 版本排期、职能分组、分组成员名册 | | `/api/security` `/api/admins` | 4 / 3 | 管理密码初始化与验证、管理员名单 | | `/api/attachments` `/api/requirements/{id}/comments` | 3 / 2 | 附件上传与预览下载、评论与回复 | | `/api/me/todo` `/api/audit-logs` | 2 / 1 | 我的待办与角标汇总、审计日志查询 | ## 文档地图 业务规则与逻辑收敛在 `docs/`,改任何模块前先定位到对应分册(`AGENTS.md` 是 AI 协作入口): | 文档 | 内容 | | --- | --- | | [AI-业务规则总览](docs/AI-业务规则总览.md) | 文档地图、领域模型、枚举字典、术语口径、魔数表、变更流程 | | [AI-权限与可见性规范](docs/AI-权限与可见性规范.md) | 鉴权、可见性、动作权限矩阵、红线清单 | | [AI-工单流程与派单规则](docs/AI-工单流程与派单规则.md) | 状态机、路线派单、Bug 闭环、归属修改、评论附件 | | [AI-查询报表与导出规则](docs/AI-查询报表与导出规则.md) | 分页筛选、统计与火焰图、待办五桶、CSV 导出、发布说明 | | [AI-前端界面与交互规则](docs/AI-前端界面与交互规则.md) | 启动与门禁、布局弹窗、控件约定、缓存串、服务端契约 | | [AI-身份会话与运维规则](docs/AI-身份会话与运维规则.md) | 飞书登录与会话、管理令牌、通知节点、催办、备份、审计脱敏 | ## 已知边界与安全提示 - **推送到公开仓库前请先处理历史**:`application.yml` 的 Git 历史里出现过飞书 `app-secret` 明文,当前值已改为环境变量注入,但旧密钥应视为已泄露——请清理历史(`git filter-repo`)并在飞书开放平台轮换后再公开。 - 定位是**内网单体**:H2 文件库 + 内存态管理令牌,不支持多实例水平扩展,重启会使全部管理令牌失效。 - 查库需先停应用再用 h2 jar 的 `org.h2.tools.Shell` 直连文件库,Web 控制台已永久关闭。 - 仓库内置了 `tools/apache-maven-3.9.6`(约 11 MB)作为无 Maven 环境的启动兜底;如果你本机已有 Maven,可以直接删掉这个目录。 - 未提供 `mvnw` 包装脚本;`.gitignore` 已排除 `/target`、`/data`、`/config`、`/push`、`/.idea`,数据库文件与凭证不得入库。 - 前端为无构建单文件,飞书 webview 缓存激进:改 `static/**` 后需重新编译并同步 `index.html` 里的 `?now=` 缓存串。 ## License 内部项目,暂未指定开源许可证。