BlueFlow Kanban

基于 PHP + MySQL + HTML + CSS + JS 的简洁看板系统，包含：

• 登录与改密
• 项目增删改查
• 需求增删改查、富文本内容、图片上传、评论
• 需求类型与状态维护
• 项目空间统计与近一周趋势曲线
• 敏捷看板视图
• API Token 授权

目录

• index.php：前端入口
• api.php：后端接口入口
• src/：认证、数据库、业务服务
• database/schema.sql：表结构与基础字典
• database/init_admin.php：管理员初始化脚本
• config/config.local.example.php：本地配置示例

初始化

1. 创建数据库：

CREATE DATABASE kanban CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. 导入表结构：

mysql -uroot -p kanban < database/schema.sql

3. 创建本地配置：

cp config/config.local.example.php config/config.local.php

然后修改 config/config.local.php 中的数据库连接信息。

也可以直接使用 .env：

cp .env.example .env

优先级从低到高是：

• config/config.php 默认值
• .env
• .env.local
• config/config.local.php

4. 初始化管理员账号：

php database/init_admin.php admin 'StrongPass!123'

5. 启动服务：

php -S 127.0.0.1:8080

打开 http://127.0.0.1:8080/index.php。

前端说明

前端入口仍是 index.php，项目已内置 React、Ant Design、Babel 等静态资源，并直接运行 assets/js/app-src.jsx。部署时不需要执行 npm install 或 npm run build，上传 PHP、CSS、JS 源文件即可。

安全说明

• 登录失败超过 5 次会触发 15 分钟限流
• 会话启用了 HttpOnly、SameSite=Lax、严格模式
• 修改数据接口默认要求 CSRF Token
• API Token 使用哈希校验，并额外保存密文副本以支持后台按需复制；列表不展示明文
• 富文本内容会做白名单清洗，外部图片仅允许 https
• 输出了基础安全头与 CSP
• 前端静态资源仅使用项目本地文件，不依赖外部 CDN；运行时 Babel 需要允许内联脚本执行

Token 调用方式

可通过以下任一方式访问接口：

• 请求头 X-API-Token: <token>
• 请求头 Authorization: Bearer <token>
• 查询参数 api_token=<token>

示例：

curl 'http://127.0.0.1:8080/api.php?endpoint=projects' \
  -H 'X-API-Token: kb_xxx'

说明

• 需求编号格式为 项目编号-序号
• 标题为空时，自动取需求内容前 8 个字
• 创建时间和开始时间默认取创建当下
• 状态切换到完成态时，自动记录完成时间
• PHP 运行环境要求 PHP 8.0+

PMS Kanban CLI

仓库里额外带了一个 Node CLI，用来轮询当前 PMS 项目的待处理需求，并通过 codex app-server 把需求交给 Codex 开发。

安装

npm install
npm link

执行完后会得到一个全局命令 pmskanban。

如果发布到 npm 后，其他机器可以直接这样安装：

npm install -g pmskanban

初始化配置

在需要交给 Codex 自动处理的项目根目录执行：

pmskanban init

这会生成一个 pms.md，其中包含：

• projectId
• pmsUrl
• token
• concurrency
• refreshIntervalSeconds

pms.md 所在目录会被当成 Codex 的工作目录。

运行

pmskanban

默认读取当前目录下的 pms.md。也可以传目录或显式路径：

pmskanban /path/to/project
pmskanban --config /path/to/project/pms.md

运行后会启动一个 TUI，显示：

• 工具名
• 项目名
• 距离下次刷新还有多久
• 当前任务表格（需求编号、需求状态、运行状态）

CLI 会按 todo -> doing -> done 同步需求状态；如果 Codex 失败，则会把需求状态改成 bug，并把错误原因和最近日志评论到该需求下。

当需求勾选“完成后自动提交 git”时，CLI 会在收尾阶段先执行 git status -s，把本次文件改动评论回该需求；如果确实存在改动，再继续 git add -A、git commit、git push。如果 pms.md 所在目录本身不是 git 仓库，CLI 会自动扫描其下的 git 子仓库，并按仓库分别提交和推送，评论里的文件列表也会带上仓库前缀。

如果任务启动前工作区已经有未提交改动，CLI 会尽量只提交本轮新增文件；一旦本轮又修改到了启动前已脏的同一文件，则只评论改动并安全跳过自动提交，不会把需求回写打成失败。这个保护逻辑同样适用于多子仓库场景。

当需求已经保存过 Codex 的会话/线程信息时，CLI 下次启动会优先恢复已有会话，再继续开发，而不是重新创建一个全新会话。

发布到 npm

npm login
npm run pack:dry-run
npm run publish:dry-run
npm publish

发布前建议确认：

• package.json 中的 name 仍然可用
• 本机已经完成 codex login
• 你希望公开发布的只有 bin/ 和 pmskanban-cli/ 两个目录