软件研发部管理工具
 
 
 
 
 
 
Go to file
mula.liu a0ced813c5 feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本
- 前端栈换成 React 19 + TS + Vite + AntD 6 + Tailwind v4 + Zustand + React Router 7 + Axios,八个视图全部迁完;旧版留在 web/legacy/
- 新增 / 修改表单统一右侧侧滑(components/FormDrawer.tsx,12 处);删除等破坏性确认仍保持弹窗
- 录入字段与「更新录入」口径对齐;长文本录入位统一富文本编辑器(内核 Tiptap 3,颜色存语义名 data-c 而非 hex,跟着主题 token 走)
- 展示端用 RichText 渲染 + 两行 clamp;app/export.py 的 plain() 在出表时统一降级成纯文本,三端换行口径一致(一个块级 = 一个换行)
- tests: 富文本存储契约与出表断言入契约测试;pytest 104 passed
2026-11-19 09:32:38 +08:00
.workbuddy/memory feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
app feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
scripts feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
tests feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
web feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
.dockerignore feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
.env feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
.env.example feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
.gitignore chore(repo): 设计规范文档 nex_design_system 移出仓库(本地参考副本,自带 .git,753K 文档不入库) 2026-11-19 09:32:28 +08:00
AGENTS.md feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
Dockerfile feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
README.md feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
docker-compose.yml feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
nex.config.yaml feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
pytest.ini feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
requirements-dev.txt feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00
requirements.txt feat: 按 nex.config.yaml 技术栈重写前端 + 表单统一侧滑 + 正文富文本 2026-11-19 09:32:38 +08:00

README.md

DMS管理平台

基于《软件开发部管理工作执行表.xlsx》构建的 DMS 管理平台。

侧栏是四个业务模块 + 四个支撑页:

模块 适用 关心什么 数据表
① 工作看板 每天进来的第一屏 三类工作本周期谁更新了、谁没动,点一条从一览看到详情 只读汇总(/api/weekly + /api/focus)
② 自研产品 NEX云桌面、AI Agent、智飞无人机平台、内部运营… 长期重点项目的迭代执行、子任务进展、风险阻塞 projects / tasks / updates
③ 定制项目 各省市客户定制子项目 商务阶段流转(签单→开发→交付→验收→计收)+ 按进度确认收入 custom_projects / custom_updates
④ 每周工作 不值得单独建项目档案的短期活儿 一条就是一件事,面板里录,归在录入周这一周,跟到完成 weekly_focus

支撑页四个:人力资源(staff,全系统「负责人」的唯一来源)、更新录入(执行 / 交付记录的唯一写入口:粘贴原文 → AI 整理 → 确认写入)、设置(周期管理、AI 配置)、权限管理(角色 × 菜单授权、账号、在线会话、操作审计)。

②③ 是两套彼此独立的项目体系(数据表也完全分开),共用一个人力资源库:项目与定制项目的「负责人」都从花名册里选,人员进出只维护一处。④ 的条目不是项目,不挂子任务与执行记录。① 只做汇总与跳转,自己不落数据。

周期管理

周期口径:自然周 + 周四归属

一周 = 自然周(周一~周日);这一周算哪个月,看它的周四落在哪个月(等价于「这一周至少 4 天在本月」)。实现见 app/constants.py 的 month_week1() 与 week_of_date(),两者互为逆运算。

2026 年的跨月边界:

周期 日期范围 说明
2026年9月第3周 09/14–09/20
2026年9月第4周 09/21–09/27 9 月就这 4 个自然周(整个 9 月 = 08/31–09/27)
2026年10月第1周 09/28–10/04 周四是 10/1 → 整周计入 10 月

所以 9/28(一)、9/29(二)、9/30(三) 写的记录统计在 10 月:9/28 一打开页面,顶栏的默认周期已经是「10月第1周」(GET /api/periods 用 week_of_date(today) 定位当期,app/routers/board.py),录入时写进去的 period_id 就是它。

推论:月口径 = 该月各自然周的并集,不等于自然月 1 号~月末(2026年9月 = 08/31–09/27、2026年10月 = 09/28–11/01)。这是「一周 7 天」+「一周不跨月」的必然结果——月份不是 7 天的整数倍,一个月只可能是 4 或 5 周(不是固定 4 周,第 5 周是合法周期,_week_period() 遇到会自动建),月底那几天总要归到某一边。

口径已经直接标在界面上,不用靠记忆:

  • 顶栏周期下拉带日期范围:2026年10月第1周(9/28–10/4)、2026年10月(9/28–11/1 · 5 周)
  • 跨月周在顶栏右侧、录入页「写入周期」旁、执行/交付记录弹窗里挂橙色「跨月周」提示,写明几天在 9 月、几天在 10 月
  • 设置 → 周期管理 有「起止日期」列,跨月的行标「跨月周」

边界规则由 tests/test_periods_projects.py::test_跨月周按周四所在月归属 锁死。要换口径(改成「周一所在月」,或记录带真实日期后「按自然日归月」)必须连带迁移历史 period_id 并核对已发布过的数字,不要只改函数。

新增周期

三个入口,都会自动接续年份:

入口 操作
顶部周期下拉 选「+ 新建周期…」
更新录入页(常规 / 定制都有) 周期下拉选「+ 新建周期…」
设置页 → 周期管理 「+ 新建周期」按钮

输入格式 9月第1周(也可写 2027年1月第1周 显式指定年份),年份按以下规则自动推断:

  • 月份 大于等于 最新周期的月份 → 用最新周期的年份(9月已有第4周时补录第1周,仍留在同年)
  • 月份 小于 最新周期的月份 → 进入下一年(8月之后建 1月第1周 → 次年)

重复创建同一周期会直接返回已存在的那个,不会产生重复数据。

删除周期

设置页 → 周期管理,表格里列出所有周期及各自的记录数。只有不含任何执行记录的空周期才能删除,已有记录的会置灰并说明原因,接口层面也会二次校验。

年份整体平移

历史数据的年份口径需要整体调整时:

python scripts/legacy/shift_year.py --dry-run      # 先预演,看清楚了再执行
python scripts/legacy/shift_year.py                # 全部 +1 年
python scripts/legacy/shift_year.py --years -1     # 反向回滚

历史一次性修数脚本统一收在 scripts/legacy/,不参与启动流程。

内部按年份从大到小更新,避免 2024→2025 撞上尚未更新的 2025;执行后会校验 sort_key 无重复,有重复则整体回滚。 执行前建议手动备份:cp data/board.db data/board.db.bak

快速开始

cd /path/to/unis_manager
./scripts/run.sh

打开 http://127.0.0.1:8770。服务默认监听 0.0.0.0:同事在局域网里用 http://<本机IP>:8770 直接访问(脚本启动时会把这行地址打印出来);只想本机访问就 HOST=127.0.0.1 ./scripts/run.sh。

首次运行 scripts/run.sh 会自动完成:检查 Python 3.10+ → 建项目内 .venv → 缺依赖自动安装(默认源失败会依次切国内镜像)→ 装前端依赖并构建 web/dist(没有 node 时用 web/legacy 旧版兜底)→ 缺 .env 时从 .env.example 生成 → 建库 → 启动并打开浏览器。已有 data/board.db 时直接复用,不会覆盖数据。

前端技术栈(nex.config.yaml 里的 nex-standard-fullstack):React 19 + TypeScript + Vite + Ant Design 6 + Tailwind CSS v4(只作工具类,颜色仍走 CSS Variables)+ Zustand + React Router 7 + Axios;源码在 web/src/。后端 FastAPI 只托管构建产物 web/dist(资源挂 /static/,深链回 index.html;没有 dist 时退回 web/legacy 的零构建旧版)。

前端命令 作用
cd web && npm install 装依赖(锁文件 web/package-lock.json,必须随仓库提交)
cd web && npm run dev 5174 热更新开发,/api 代理到本地后端
cd web && npm run build tsc --noEmit + Vite 构建,产出 web/dist
cd web && npm run typecheck 只做类型检查

scripts/run.sh 里对应:源文件比 web/dist 新就自动重建;WEB=0 跳过构建、WEB=force 强制重建、NPM_REGISTRY=... 换 npm 源。

启动方式与排错

场景 命令
正常启动 ./scripts/run.sh
报 permission denied chmod +x scripts/run.sh 后重试(不要用 sudo)
不想改权限 bash scripts/run.sh
缺 Python / 依赖 脚本自动安装;不想自动装就设 AUTO_INSTALL=0,脚本只打印命令
缺 Node / 前端构建失败 装 Node 20+ 再跑;只想先把服务跑起来可以 WEB=0 ./scripts/run.sh(界面用 web/legacy 旧版)
换端口 PORT=8771 ./scripts/run.sh
关闭热加载 DEV=0 ./scripts/run.sh(默认是开着的)
不自动开浏览器 NO_OPEN=1 ./scripts/run.sh
提示"端口已被占用" 原窗口 Ctrl+C,或 lsof -ti:8770 | xargs kill 后重跑
用 Docker 部署(不装 Python) ./scripts/deploy.sh up,见下面「Docker 部署」

⚠️ 不要用 sudo 启动:数据库文件会变成 root 属主,后续写入会失败。

热更新(默认开启):uvicorn 监听 app/**.py 与 .env,改后端即重启。 改前端走另一条路:cd web && npm run dev(Vite 自带 HMR,/api 代理到后端),或改完 npm run build 再刷新——产物文件名带哈希,浏览器不会拿旧版。 DEV=0 ./scripts/run.sh 关掉后端热重载;data/*.db 的写入不会触发重启。旧零构建版(web/legacy/)的 livereload.js 只在没有 web/dist 时生效。

手动分步执行(等价于 scripts/run.sh 干的事)

python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt
cd web && npm ci && npm run build && cd ..      # 前端产物 web/dist
./.venv/bin/python scripts/init_db.py
./.venv/bin/python -m uvicorn app.main:app --port 8770

Windows 把 .venv/bin/ 换成 .venv/Scripts/。

从旧 Excel 还原历史数据(一次性,相关脚本已归档到 scripts/legacy/):

./.venv/bin/python scripts/import_excel.py "<软件开发部管理工作执行表.xlsx>" --reset
./.venv/bin/python scripts/legacy/migrate_custom.py
./.venv/bin/python scripts/import_staff.py "<软件开发部人员名单.xlsx>"

现在 scripts/run.sh 首次启动只建空库,不再自动导入 Excel。已有数据库的机器直接把 data/board.db 带过去即可。

Docker 部署(换机器 / 上服务器)

不想装 Python,或者要放到服务器上常开,用 Docker:

cd /path/to/unis_manager
./scripts/deploy.sh up            # 构建镜像 + 后台启动 + 等健康检查

打开 http://127.0.0.1:8770(局域网访问 http://<本机IP>:8770,监听地址由 .env 的 HOST 控制,默认 0.0.0.0)。首次启动自动建表、预置分类,并创建内置角色与 admin 账号(密码见 .env)。

文件 作用
Dockerfile 运行镜像:装依赖 + 拷 app/ web/ scripts/;启动时先跑 init_db.py(幂等)再起 uvicorn
docker-compose.yml 编排:./data 挂进容器存数据库、HOST_PORT 控对外端口、restart: unless-stopped 随 Docker 自启
scripts/deploy.sh 命令封装:up / update / restart / down / logs / status / backup / mirror,顺带检查 docker 是否在跑、.env 与 data/ 是否存在,并在构建前定好基础镜像与 pip 源
.dockerignore 保证 data/、.env、.git 不会被烤进镜像
场景 命令
改完代码上线 ./scripts/deploy.sh update(重建镜像并替换容器)
改了 .env(AI Key / 端口) ./scripts/deploy.sh restart
看日志排错 ./scripts/deploy.sh logs
看状态与健康检查 ./scripts/deploy.sh status
停止(数据保留) ./scripts/deploy.sh down
换对外端口 .env 里 HOST_PORT=8080,再 ./scripts/deploy.sh up
裸 compose 命令 docker compose up -d --build / docker compose down
构建时基础镜像 / pip 下载超时 ./scripts/deploy.sh mirror 重探,或手工指定 PIP_INDEX_URL=... BASE_IMAGE=... ./scripts/deploy.sh up(见下「国内网络加速」)
把现有数据带到新机器 ./scripts/deploy.sh backup → 拷到目标机 data/board.db → ./scripts/deploy.sh up

国内网络加速(docker.io / pypi.org 连不上时)

国内构建会撞两道互不相干的墙,得分开治,只治一道必然还剩一道:

卡在哪 典型报错 治法
① 守护进程拉基础镜像 failed to resolve source metadata for docker.io/library/python:3.12-slim: ... TLS handshake timeout 用本地已有的镜像(BASE_IMAGE= 指定),或先 docker pull / 给守护进程配 registry-mirrors
② 构建容器里装依赖 [4/8] RUN pip install ... -i https://pypi.org/simple 非零退出 换 pip 源 PIP_INDEX_URL(清华 / 阿里 / 腾讯)

./scripts/deploy.sh up 构建前把这两道都定下来,原则是能本地解决就不联网:

  • 基础镜像只看本地有没有:BASE_IMAGE 指定的镜像在本地 → 直接用;只有同名 tag(如 python:3.12-slim)→ 也用(仓库前缀只是当初从哪儿拉的,镜像是同一份)。本地确实没有才试拉一次(守护进程配的 registry-mirrors 在这一步生效),还拉不到就直接报错停下并打印补救命令——不去逐个试加速站,那种循环只会白等几分钟。
  • pip 源:在构建用的容器里真 urlopen 一次逐个试(容器网络 = 构建网络,比宿主机 curl 准),默认清华源。
  • 定下来的值只 export 给本次构建,不写回 .env(.env 在 git 里,把某台机器的地址带到另一台机器正是故障源)。
./scripts/deploy.sh up                  # 定源(本地有镜像就不联网)→ 构建 → 等健康检查
./scripts/deploy.sh mirror              # 重探一次 pip 源,并打印可写进 .env 的两行

别把某台机器上的 BASE_IMAGE 前缀提交进仓库。 换机器后那个前缀对应的镜像本地不存在,构建就会卡在 load metadata;这行留空或写裸 python:3.12-slim,让每台机器自己的镜像说了算。

不想用脚本,等价的两条 build-arg:

docker compose build \
  --build-arg BASE_IMAGE=python:3.12-slim \
  --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
docker compose up -d

几个必须知道的点:

  • 基础镜像拉成功 ≠ 构建能过:docker pull 只治①,容器里的 pip install 照旧撞 pypi.org,必须另外给②换源。
  • shell 里的 HTTP(S)_PROXY 对构建没用:Docker 守护进程和构建容器都不读宿主机的代理变量。要走代理得在 Docker Desktop → Settings → Resources → Proxies 里配 http://host.docker.internal:7897(端口换成你本机代理的)。
  • 境外机器 / 内网有自建源:CN_MIRROR=0 ./scripts/deploy.sh up 跳过 pip 探测,源完全由 .env 说了算。
  • 目标机完全不能上网:走离线路。docker save -o unis-board.tar unis-board:latest → 拷过去 docker load -i unis-board.tar → NO_BUILD=1 ./scripts/deploy.sh up(跳过构建直接用本地镜像)。
  • 构建失败时脚本会自己打印一份排查清单(scripts/deploy.sh 的 build_hint),照抄命令即可。

几个坑:

  • 数据只落在 ./data:重建镜像、down 再 up 都不动数据;备份依旧是拷走 data/board.db。
  • 时区必须设:容器默认 UTC,而周期/周次/入库时间都按本地日期算,所以 compose 固定传 TZ=Asia/Shanghai,别删。
  • 容器内端口固定 8770:.env 的 PORT 是本机 scripts/run.sh 用的,compose 里覆盖成 8770;要换端口只改 HOST_PORT。
  • 别和 scripts/run.sh 同时跑:一是 SQLite 是文件库,同一份 board.db 不要同时被本机进程和容器读写;二是默认两边都监听全部网卡的 8770(run.sh 的 HOST=0.0.0.0 × compose 的 HOST_PORT=8770),后启动的那个会直接撞端口。两者要共存就给一边换端口:HOST_PORT=8899 ./scripts/deploy.sh up 或 PORT=8899 ./scripts/run.sh。
  • 换 MySQL:放开 Dockerfile 里 pymysql 那行重新 build,再把 .env 的 DATABASE_URL 指过去(见「迁移到 MySQL」)。

带着现有数据部署

镜像里故意不含数据(.dockerignore 排除了 data/),容器读的是宿主机挂载进来的 ./data/board.db,所以:

  • 就在本机这个目录部署 → 什么都不用做,./scripts/deploy.sh up 起来读的就是当前这份库;连 user_sessions 里的登录态都延续,别人不用重新登录。
  • 换一台机器部署 → 先把数据取出来,落到目标机的 ./data/board.db:
./scripts/deploy.sh backup                                    # 一致性快照 → data/backups/board-YYYYmmdd_HHMMSS.db
scp data/backups/board-*.db user@host:/srv/unis_manager/data/board.db
ssh user@host 'cd /srv/unis_manager && ./scripts/deploy.sh up'
  • 数据库不在 git 里(data/ 已忽略),git clone 不会带数据;要迁移请用 ./scripts/deploy.sh backup 的快照(走 SQLite 备份 API,本机服务正在写也能拿到一致的库)。
  • 启动时的 init_db.py 和 ensure_seed 只会补缺失的表 / 分类 / 内置角色,users 非空就不再创建 admin,不会覆盖或清空任何数据。实测:拿当前生产库快照起容器,启动前后逐表行数完全一致,123 个定制项目、22 名人员、老 token 全部照常可用。
  • 目标机上的 ./data 属主要和运行容器的人对得上(compose 以 root 跑则无此顾虑);SQLite 是文件库,同一份库别让两个实例同时写。

功能

1. 工作看板

进来第一屏:三类工作在这一页从「一览」点到「详情」,左栏挑一条,右栏跟着联动。

区域 内容
顶部 KPI 重点项目(含本期已更新数)/ 重点项目未更新 / 本周重点工作(本周到期的重点工作条数,脚注「逾期 N 条 · 已完成 N 条」)/ 执行记录 / 定制合同额(含项目数与本期计收)/ 风险阻塞
左栏 三组清单,顺序固定:① 本周工作重点(列表,逾期的置顶)② 重点项目(列表:is_key 的项目,另含本期补了执行记录的非重点项目,条目前用 ★ 区分)③ 定制项目——只给一个入口「本周定制项目动态」,左栏不铺清单(100 多个项目会淹没看板),点开才在右栏列本周有动态的。组头显示条数与「几个已更新 / 几条逾期 / 本周动态几个」;每条带负责人、状态或阶段、本期摘要、风险条数,本期有记录的点亮标记
右栏 点左栏任意一条即可联动。重点项目 → 本期执行记录 / 进度与状态(含子任务)/ 近 8 期趋势;定制项目入口 → 本周动态总览(顶部标签:本周新增 / 本周验收 / 有交付动态 / 合同额合计 / 本期计收,下面分「本周新增」「本周验收」「本周有变化」三段,每条带阶段、负责人、金额、本期计收与摘要),点某一条再下钻到该项目 → 交付环节五段条 / 财务跟踪四联卡 + 开票·回款行内输入 / 本期交付记录 / 更早的交付记录,改开票、回款、环节日期即时保存(改日期会自动推进商务阶段);每周重点工作 → 只读的说明与状态,要改点「修改」开抽屉
工具栏 「负责人」筛选(只过滤左右两栏清单,不改变顶部 KPI)、「导出 Excel」(导出顶栏所选周期 / 月份的全部执行记录,不带负责人条件);顶栏可切周 / 月视图(月视图自动汇总该月所有周)。「列入全部在途」开关(all_custom)在右栏定制总览的头部

数据分两路:GET /api/weekly?period_id=|year&month&owner=&all_custom= 一次返回重点项目清单 + 定制项目清单 + 顶部 KPI(含 custom_new 本期新入库数、custom_updated 本期有交付记录数);「本周工作重点」不在 /api/weekly 里,前端并发取 GET /api/focus 后合并,分堆也在这一步判定(按条目的录入周:本周录入的 + 更早周次标了「延期」又没做完的结转条目)。

定制项目的口径:/api/weekly 返回本期有交付记录、被标为重点、本周期新入库(is_new:入库日期落在本周期首末日之内)、本周期新下单(sign_date 落在本周期)或本周期已验收(update_date 落在本周期且项目状态为「已验收」)的定制项目;右栏总览默认列「本周新增」「本周验收」「本周有变化」三段,其中前两段与「定制项目 → 本周进展」的「新增项目 / 验收情况」口径完全一致(前者按「下单时间」、后者按「更新时间 + 状态=已验收」),其余只在组头计数里出现,并在底部提示「另有 N 个在途定制项目本周没有动态」。勾选总览头部的「列入全部在途」后,后端补上处于在途阶段(商机 → 已验收)的项目,总览多出一段「其他在途项目」。头部几枚标签与「合同额合计」只加总当前列出来的行(同一项目同时落在两段时只算一次),勾与不勾数字会跟着清单变。

2. 自研产品(项目管理)

长期重点项目(projects + tasks + updates)。执行记录的写入逻辑没变,仍旧统一走「更新录入」。

模块 说明
项目管理 表格展示分类、负责人、状态、进度、更新情况(标签只在详情抽屉里维护,列表不放,避免挤占名称列);列表只读,行内不放任何输入框和下拉,每行只有 详情 / 修改 / 归档 三个按钮(操作列吸附在表格右侧,横向滚动也不会被挤出可视区);负责人筛选下拉来自人力资源库;支持新建与「含归档」筛选。详情抽屉里的周期反馈可切「按周 / 按月」与「本周 · 近 4 周 · 近 12 周 · 全部」(按月为「本月 · 近 3 月 · 近 6 月 · 全部」),用 ‹ › 翻页看更早的周期,默认跟随顶栏选中的周期

项目维护操作

操作 说明
面板分区 抽屉用标准对话框式标题栏:标题在左(下面一行副标题),基础信息的操作按钮成排在右,✕ 在最右,按钮条嵌在标题栏里(不悬浮、不吸顶,滚动时跟着标题栏常驻)。详情档是「删除 · 归档/恢复 · 标记重点 · 修改」,修改与新增档是「取消 · 保存/添加」,主按钮永远在最右、危险动作在最左,按钮文字不再重复对象名(标题栏已经写了是哪个项目/条目)。附表的写入只有一处入口:附表标题下的「添加执行记录」,它跳到「更新录入」并带上该项目与顶栏当前周期——抽屉里不另做一套基础信息之外的录入表单,避免两条路写出两份数据;改某一条已有记录用的是行内「修改」,走全站唯一的记录弹窗(openUpdateDialog,看板右栏与定制抽屉共用)。基础信息的按钮在标题栏、附表的更新按钮在附表上方,两类按钮不在同一个位置混着放;编辑与新增档的报错信息显示在正文最上方;周期反馈上方的 按周/按月 + 本周/近 4 周/… 标成「查看范围(只读筛选)」,只翻看不改数据
改名 改名就是改基本信息:在详情面板点「修改」,表单第一行即项目名称(项目管理与定制项目同一套逻辑)。名称非空校验 + 重名检测,失败信息显示在面板正文最上方,不弹提示跑路
负责人与团队 多负责人只适用于重点项目:重点项目可以指定多个负责人与团队成员,定制项目只有一个交付负责人(单人下拉)外加团队成员。人名一律从人力资源库下拉里选。界面上负责人不分主次:名单横向排开自动换行,每一位都带 × 可删(没有「主」标记、没有不给删的首行),「+ 添加负责人 / + 添加成员」跟在名单末尾。名单只在详情抽屉的「修改」档维护;只读处一律一排对等的小标签:重点项目的列表与详情把负责人摆成对等的一排,定制项目的列表与详情只显示一个交付负责人加团队成员标签。存储与统计口径不变:重点项目 owner 字段仍是 owners[0](删掉第一位就由后一位顶上),看板、导出、人力负载与 KPI 按它归属;重点项目所有负责人都算命中,定制项目按交付负责人命中;团队成员不参与该筛选
归档 项目从看板与列表默认视图中隐藏,数据完整保留;勾选「含归档」可查看,随时可恢复
删除 高危操作:弹窗列出将连带删除的子任务数与执行记录数,并且必须逐字输入项目名称,「永久删除」按钮才会点亮。删除后不可恢复,仅想隐藏请用归档

定制项目的「项目明细」表同理:列表只读,操作列只有 详情 / 修改 / 归档,改名 / 名单 / 删除都在抽屉里做。

项目合并

把两个项目合并成一个(例如把「智空无人机平台」并入「智飞无人机平台」):

python scripts/legacy/merge_project.py --from "智空无人机平台" --to "智飞无人机平台" --dry-run
python scripts/legacy/merge_project.py --from "智空无人机平台" --to "智飞无人机平台"
  • 子任务同名 → 归并到目标项目的同名子任务,执行记录一并转挂
  • 子任务仅源项目有 → 直接转到目标项目名下(保留原名)
  • 分类 / 负责人 / 描述 / 标签仅在目标缺失时继承
  • 合并后按最新记录回算目标项目的进度与状态
  • 执行前建议备份:cp data/board.db data/board.db.bak

3. 定制项目

三个页签,都跟着顶栏周期走:项目总览(默认)· 本周进展 · 年度任务。 统计条与年度任务只认 GET /api/custom/finance 一个数据源,口径见「财务统计口径」。

页签 / 模块 说明
项目总览 标题栏下一排统计条:已下单项目/合同额、本季度下单、本年新增下单、本季度验收、本年验收(金额按「万」显示,脚注项目数)。下面是按更新时间倒序的只读总表:项目名称 / 项目ID / 下单时间 / 项目归属 / 办事处 / 行业 / 市场下单人天 / 订单金额 / 市场责任人 / 项目状态 / 进度 / 验收时间 / 推动验收计划 / 风险值 / 更新时间;下单时间、订单金额、更新时间三列表头可点着排序。筛选只有关键字 + 归属 + 区域 + 项目状态 + 风险值。台账里认不出的写法(下单时间识别不了、已验收没填验收年度)在标题栏挂一枚提示标签,不挡事
本周进展 更新时间落在顶栏选中周期内的项目;统计条给「验收情况 / 新增项目 / 进行中项目」,其中新增与验收和工作看板右栏共用同一套口径(customWeeklySections),两处数字必然一致
年度任务 四个季度的计收目标(万元)与完成情况对照。完成额按「验收年度 + 验收季度」归集、下单按下单时间所在季度归集,跨年不会串;默认只读,点「编辑」才能改,改数字实时重算完成率与合计,保存走 PUT /api/custom/annual-targets?year=
详情抽屉 分「详情 / 修改」两档:详情只读(基础信息 + 收入确认四联卡 + 开票 / 回款行内输入 + 交付记录 + 阶段流转时间线),修改才给表单(名称、手动确认比例、交付环节日期、区域、验收年度 + 验收季度成对填写、开票与回款金额)。交付负责人是单人下拉,从人力资源库里选;「添加交付记录」在交付记录区里,一个弹窗录本周期一条
归档 归档后不再出现在总览与统计中,历史周期记录完整保留,随时恢复

4. 每周工作(重点工作清单)

不值得建项目档案的短期活儿:一条就是一个活儿,不用先建项目,录进来就能按周跟踪。

区块 说明
新增 工具栏「+ 新增重点工作」开独立面板(列表顶部那张内嵌录入卡已撤掉):工作内容(必填,一句话说清干什么)/ 说明(可选)/ 录入周(只读=顶栏当前选中的那一周,切周再录就归到那一周)/ 预计完成时间(日历日期,只是目标日期,不决定条目归到哪一周)/ 执行状态(取 constants.STATUSES)/ 结果反馈 / 是否延期(人工开关)
列表 工作内容 / 说明(截断预览)/ 预计完成时间(下面小字标「录入 X月第N周」)/ 状态(标了延期且没完成的挂红色「延期」徽章)/ 更新日期 / 操作 详情 · 修改 · 归档 · 删除——和两张项目列表同一套规矩:列表只读,行内不放输入框
筛选 本周 / 延期 / 已完成 / 全部 四个堆(chip 上实时显示各堆条数)+「含归档条目」;顶栏切周即换基准周,工具栏标明「本周/延期按录入周统计」;顶部全局搜索同时匹配工作内容与说明
详情抽屉 同样分「详情 / 修改」两档,基础信息的按钮全在抽屉标题栏右侧的按钮条上:详情档是「删除 · 归档 · 修改」,修改与新增档是「取消 · 添加/保存」,报错信息显示在正文最上方。点「修改」才出表单,录入周只读(改预计完成时间不会把条目搬去别的周)。重点工作条目没有附表,所以抽屉里不出现绿的更新条
删除 列表行与抽屉顶部都能删,走同一个确认弹窗,并提示「只是这周不再跟进?请改用归档」。条目不挂子任务与执行记录,不要求逐字输入名称——逐字输入项目名称只用在项目管理与定制项目的项目删除上
导出 右上角「导出 Excel」→ GET /api/export/focus,带上当前筛选条件
联动 工作看板左栏第一组「本周工作重点」与 KPI「本周重点工作」读的就是这张表;看板右栏点条目给只读详情,改内容走抽屉

分堆口径(基准周 = 顶栏选中的那一周,一律按录入周算,和预计完成时间无关):录入周等于基准周 → 本周;录入周早于基准周且「是否延期」打开且未完成 → 延期(上周及更早没做完的活儿结转进来);状态为「已完成」→ 已完成(交叉视图,条目仍留在自己那一周)。 「更早周次录入、没标延期又没完成」的条目不进当周视图,只在全部里查得到——所以每周收尾时,没做完的记得勾上「延期」,它才会结转进下周。库里不存「逾期」字段,延期是人工开关。

5. 权限管理

角色 × 菜单 授权矩阵、账号与角色分配、在线会话、操作审计四个区块,一个页面四个页签。 权限模型、内置角色与防锁死规则见「权限(RBAC)」,这里不重复。 只有拿到 rbac 可编辑的账号能看到这个菜单。

人力资源库

侧栏「人力资源」,是全系统负责人姓名的唯一来源(staff 表)。

区块 说明
顶部 KPI 在册人数与带项目人数、各归属小组人数、人员归属(汇智 / 云数 / 外服)分布,以及花名册外的负责人核对(历史数据里对不上花名册的人名,一个都不藏)
花名册 姓名 / 归属小组 / 人员归属 / 说明 + 该人的在管项目数、定制项目数、定制合同额、名下待计收、最近更新;小组与归属可行内改(下拉),说明行内编辑失焦即存
筛选与导出 在编 / 已归档 / 全部 + 按小组筛选;「导出 Excel」按当前筛选导出
新增 弹窗录入:姓名必填且全库唯一,小组与归属下拉取自 constants.STAFF_GROUPS / STAFF_AFFILIATIONS
改名 走「编辑」改姓名时,名下项目与定制项目的负责人、其他负责人、团队成员一并同步改掉,历史数据不会断链
归档 / 恢复 归档后不再出现在「负责人」下拉里,但历史项目仍完整保留其负责人;随时可恢复。离职人员用归档,不要用删除
删除 名下还挂着项目或定制项目时接口直接返回 400 并说明原因,防止把在管项目变成无主项目

导入名单(表头按名称匹配:序号 / 姓名 / 归属小组 / 人员归属 / 说明):

python scripts/import_staff.py --dry-run   # 只看解析结果
python scripts/import_staff.py             # 增量导入(同名跳过,不覆盖页面上的编辑)
python scripts/import_staff.py --reset     # 清空后重新导入
python scripts/import_staff.py <xlsx>      # 指定别的文件(不会随启动自动导入)

不传路径时默认读 data/import/软件开发部人员名单.xlsx,也可以用 STAFF_XLSX 环境变量指定。

负责人下拉(ownerSelectHtml)在项目新建/详情、定制项目新建/详情、工作看板等位置统一使用,选项来自花名册: 已归档的人不再作为可选项出现,只有他本来就是这条记录的负责人时才带「(已归档)」标注出现一次; 历史数据里花名册没有的人名同样补一个「(不在花名册)」选项,保证打开老项目不会把负责人改没。 多负责人与团队成员复用同一个下拉(peopleEditorHtml,现在只有重点项目的抽屉用它):人名下拉横向排开、自动换行,选项同样只有花名册里的人,所以新增成员不需要另外维护一份名单;名单里的每一位都带 × 可删,界面上不区分主次。定制项目的负责人是普通的单个 ownerSelectHtml 下拉,只有团队成员用这套名单编辑器。

入库时间

定制项目新增「入库时间」字段,当前口径为 该项目最早记录所在周期的第一天(周一):

  • 优先取原始《项目明细表》台账中该项目所在的周(该列是稀疏填写的,导入时按周分组向下继承)
  • 台账没有的,取《周工作情况总结》「定制开发」块中该项目首次出现的周
  • 再没有,依次退回 custom_updates 最早记录周期 → 项目所属周期 → 记录创建日期

周期换算规则:第 1 周 = 第一个周四落在本月的那一周(见上「周期口径」),第 N 周顺延 7×(N-1) 天,取该周周一。 例如 2026年8月第4周 → 2026-08-24(8 月第 1 周是 08/03–08/09);2026年9月第1周 → 2026-08-31(周一在上个月,照样算 9 月第 1 周)。

字段可在明细表中直接改,也可在抽屉里改;重新计算用:

python scripts/legacy/add_entry_date.py --dry-run   # 预演
python scripts/legacy/add_entry_date.py             # 回填(跳过已有值)
python scripts/legacy/add_entry_date.py --force     # 全部重算

区域(省级行政区)

  • 编辑时是规范下拉,34 个省级行政区按大区分组(华北 / 东北 / 华东 / 华中 / 华南 / 西南 / 西北)
  • 列表筛选下拉同样使用规范名称,只列出实际有项目的区域
  • 历史数据里若出现「内蒙古自治区」这类非规范写法,保存时会自动归一为「内蒙古」
  • 早期从项目名推断的区域(infer_region)与标准列表口径一致,无需迁移

权限(RBAC)

侧栏每个菜单都是一个权限点,授权 = 角色 × 菜单 × 级别;账号不直接挂菜单,只挂角色。

概念 取值 说明
菜单 board 工作看板 · projects 自研产品 · custom 定制项目 · focus 每周工作 · staff 人力资源 · intake 更新录入 · settings 设置 · rbac 权限管理 见 constants.MENUS,顺序即权限页里的列顺序
级别 空 = 看不到 / ro 只读 / rw 可编辑 没授权的菜单侧栏不出现,接口也进不去;ro 能看列表与详情,所有写接口一律 403
  • 多角色取并集、同级取高:一个账号可挂多个角色,同一菜单只要有一个角色给了 rw 就是 rw(constants.merge_levels)。
  • 双端校验:前端 can() / canW() 只负责把按钮藏起来,真正的门在接口上—— 每个路由都挂了 security 的权限依赖,按路径首段映射菜单(SEGMENT_MENU), 读请求要求 ro、写请求要求 rw;越权返回 403 并记一条 audit_logs(action=deny)。 /api/auth/*、/api/meta 这类只要求登录,不看菜单,否则无法登录与自助改密。 录入页跨菜单依赖单独开口:GET /api/custom/meta、GET /api/custom/projects、POST /api/custom/updates、POST /api/custom/ai/parse、POST /api/custom/ai/commit 按 custom / intake 两者中较高的级别判定——只有「更新录入 rw」的账号也能录入定制项目; 定制本体(详情 / 新建 / 修改 / 归档)仍严格走 custom。新增这类跨菜单读接口要同步改 security.guard 的 assist 白名单。
  • 内置角色:管理员(全部 rw)、部门成员(业务菜单 rw,设置与权限只读/无)、只读访客(除权限外全部 ro), is_builtin 标记,不能删除。
  • 不会被锁死:系统始终保证至少有一个「启用 + 权限管理可编辑」的账号; 一个都没有时 security.ensure_seed 会把「管理员」角色补给最早的账号并在启动日志里提示。
  • 改权限即踢会话:改角色授权 → 踢掉该角色下所有账号的会话;改/停账号 → 踢掉该账号的会话。 旧 token 不会继续带着旧权限跑。
  • 会话:登录发 32 位随机 token,存 user_sessions(有效期 SESSION_DAYS,默认 30 天), 只通过 HttpOnly Cookie unis_session 下发(JS 读不到,前端不存 token); 权限管理页可查看全部在线会话并单独吊销。
  • 操作审计:写操作与登录 / 登出 / 越权都落 audit_logs(谁、什么时间、哪个菜单、什么动作、返回码、IP), 权限管理页可按菜单、动作、天数筛选。
  • 首个管理员账号来自 .env 的 ADMIN_USERNAME / ADMIN_PASSWORD(默认 admin / admin123,登录后请立刻改密码)。

界面设计语言

前端是 Vite 构建的 React + TypeScript 应用(源码 web/src/,Ant Design 出控件、Tailwind v4 出工具类、项目 token 出一切视觉值)。设计口径固定如下,新增页面请沿用:

  • Token 只有一个来源:颜色 / 圆角 / 阴影 / 间距 / 控件高度 / 层级 / 动效时长全部在 web/src/styles/tokens.css 顶部的 :root(--text*、--surface-*、--primary*、--success/--warning/--danger、--radius-*、--sp-*、--ctrl-h-*、--z-*、--dur-*)。组件里不再出现第二套 hex;业务数据色(项目分类色、阶段色)由 web/src/domain/ink.ts 的 INK 常量注入 style={{ "--c": ... }},JS 模板里不写裸色值。文本对比度按 WCAG AA(≥4.5:1)取值。
  • tinted 底板只有一个算法:.pill / .tag-mini / .arch-badge 只吃 --c,底色与文字色在 CSS 里用 color-mix() 派生;旧的「背景 hex + 文字 hex」成对写法已废,新增状态标签照 --c 办理。
  • 弹层与焦点一条路:一律用 AntD @B@Modal@B@ / @B@Drawer@B@(自带 @B@role="dialog"@B@、焦点陷阱、Escape 关闭、关闭后焦点归还触发元素),不再手写弹层与焦点栈;抽屉里再开弹窗由 AntD 的层级接管。图标按钮必须有 @B@aria-label@B@(@B@title@B@ 不算名字)。
  • 新增 / 修改一律右侧侧滑:表单类面板统一走 @B@components/FormDrawer.tsx@B@(头部 @B@.dlg-title@B@ + 可选副标题、正文 @B@.drawer-body@B@、底部固定「取消 + 保存/创建」右对齐、层内错误用行内 @B@Alert@B@、提交中按钮 loading 且不许 Esc 关闭);删除等破坏性确认仍用 @B@modal.confirm@B@(危险按钮 danger),不要为了统一把确认框也做成抽屉。窄屏 (<=640) 表单抽屉给全宽。
  • 录入字段跟着「更新录入」走:同一个对象在各模块里的表单字段与「更新录入」入口一致(自研:执行内容(正文,原文照录)/ 一句话摘要 / 总进度 / 整体状态 / 风险 / 阻塞 / 下一步计划;定制:执行内容 / 项目状态 / 开发进度(%)/ 本期新增计收(万元)/ 本期新增下单(万元)/ 一句话摘要 / 风险 / 阻塞 / 下一步计划)。模块特有的轴(自研的「子任务」)可以多不能少;措辞改了要四处一起改。
  • 正文富文本一套约定:「内容」这类正文支持加粗 / 下划线 / 斜体 / 语义色,用 components/RichEditor.tsx,内核是 Tiptap 3(ProseMirror):回车分块、选区、中文输入法、撤销栈这几件事手写 contentEditable 反复出问题,交给成熟的编辑器内核。工具栏是我们自己排的(Tiptap 是 headless,样式跟着 NEX 走):图标按钮 加粗 / 斜体 / 下划线 + 颜色按钮(A + 当前色条 + ▾,弹出色板:只有色块不写中文,名称在 title / aria-label 里,第一个是「无色」= 摘色) + 清除格式;图标进唯一图标层 icons/paths.ts(bold / italic / underline / eraser / chevron-down),不自建第二套图标。颜色是挂在自己写的 data-c 属性上的语义色 mark(不用官方 Color,因为它存 hex,会脱离主题 token),重复上色是替换语义; 产出只写 <b>/<i>/<u>(加粗斜体特意扩展成短标签,<strong>/<em> 只收不发);回车 = 一行一段 <p>(Shift+回车 = 行内 <br>),空行存 <p><br></p>——不带 <br> 的空段落在展示端没有行盒,编辑看得见、看着看不见就又不一致了; 三端换行口径统一:一个块级 = 一个换行(utils/richtext.richToText 用 DOM 走一遍,app/export.py.plain() 先把相邻 </p><p> 合成一个换行),别拿「开标签闭标签各断一次」那种写法,否则每行后面凭空多一个空行,展示一律 components/RichText.tsx(先消毒再注入);项目里所有长文本录入都用这一个组件(执行/交付记录正文、风险 / 阻塞、下一步计划、定制备注、重点工作说明与结果反馈、更新录入的原始内容与整理结果正文),单行字段(摘要、工作内容)保持普通输入框。列表里的预览不要再按字数硬切——那会把富文本压成纯文本,用户会以为格式没生效;改成 <RichText className="clamp"/> 两行截断,格式留着。存储就落在原来的 content 文本列里,只允许 <b> <i> <u> <br> <span data-c="danger|warning|primary|success|muted">;颜色存语义名不存 hex,渲染时映射回 var(--*) token,改主题会跟着变。要纯文本的地方(关键字匹配、截断、AI、Excel)走 utils/richtext.ts 的 richToText / 后端 app/export.py 的 plain()。「原始内容」粘贴框同样是富文本,但发给解析器 / AI 的那一份先转回纯文本——规则解析按行找「风险 / 下一步」,标记会打断它;入库的正文仍带标记。
  • 状态不只靠颜色:选中 / 按下 / 当前项写 aria-current / aria-selected / aria-pressed,CSS 用属性选择器出强调条与勾选图标;可排序表头是 <th aria-sort> + .th-sort 按钮,页签组是 role="tablist" + .tabpanel。
  • 加载与忙态统一:列表 / 卡片占位用 AntD Skeleton(<TableSkeleton/> / <CardSkeleton/>,不写「加载中…」文本),取数一律 useAsync()(自带竞态守卫 + loading / error);耗时动作 loading / disabled + aria-busy,导出走 download(url, btn, message);结果只经 message(AntD App 上下文,role="status"),表单错误槽是 <Alert role="alert">。
  • 断点登记在 CSS 顶部注释:1180(周看板转单栏)/ 1100(侧栏转抽屉)/ 900(顶栏换行、抽屉全宽)/ 780(表单与人员卡换行)/ 640(触控尺寸、弹窗转底部抽屉)。CSS 不能在 @media 里用 var(),改断点必须同步那条注释。动效一律 ≤280ms 且尊重 prefers-reduced-motion;forced-colors 下兜底焦点环。
  • 禁用「彩色描边」:卡片、列表、步骤条、表格一律中性灰边框(--border / --border-strong)或无边框,不用圆角多色边框表达状态。
  • 重点色只出现在三处:图标、关键数字/文本、小面积 tinted 底板(.ic-badge、.tag-mini、.kpi.accent-*)。状态色(statusMeta)与阶段色(stageMeta)是唯一配色来源,避免各页面自己调色。
  • 图标系统:web/src/icons/ 内置 52 个 24×24 线性 SVG(每个都被界面或状态/阶段/标题映射引用,死图标随手删),stroke=currentColor,颜色跟着文字走。对外 API: <Icon name="wallet" /> 裸图标;<IconBadge /> 图标 + tinted 底板(KPI 用);<StatusIcon/> / <StageIcon/> / <PipeIcon/> 按状态·阶段·交付环节取图标; nameOfStatus() / nameOfStage() / nameOfPipe() 出图标名;iconForTitle() / iconForEmpty() 按关键词挑图标。
  • 自动图标:iconForTitle() 在渲染期按标题关键词给 <PanelCard title> / <SectionTitle> 补前导图标(旧版是 MutationObserver 全局扫 DOM,现在组件自己算,没有副作用);标题里自带 <Icon /> 时不再补第二个。
  • 交付环节图标按 code 取:后端 CUSTOM_PIPELINE 下发的字段是 code(不是 key),前端一律 Ico.pipe(s.code);写成 s.key 会静默退化成通用圆点。
  • 表格防竖排:标签(.pill / .tag-mini)与列头一律 white-space:nowrap,容易挤窄的列(区域、负责人)在 columns 上加 className: "nowrap";宽表交给 AntD Table 的 scroll={{ x }} 横向滚动 + 操作列 fixed: "right",不给它换行挤成一竖。
  • 抽屉不被内容撑破:.form-row > div { min-width: 0 }(grid 子项默认 min-width:auto,会被交付环节步骤条撑出整表横向滚动),步骤条本身 flex:1 1 132px(132px = 日期输入框含日历图标的最小可用宽度)。
  • 报错一律中文:Pydantic 422 与未捕获 500 在 app/main.py 的 exception handler 统一换成中文 detail(「提交的数据有误:…」/「服务器内部错误…」),前端 api() 原样 toast,界面不中英夹杂。新增 /export/* 必须登记 security.EXPORT_MENU 权限归属,未登记一律 403(fail-closed,防「忘挂权限 = 登录即可下载」)。
  • 反馈矩阵(只有这三条通道):弹窗内报错 → modalError()(#mErr 行内提示);抽屉表单报错 → formError("fdErr|cdErr|dwErr", msg)(行内提示,传空串清除);其余一律 toast();破坏性动作只走 confirmDialog()。异步写处理器先本地 try/catch 提示并中断后续刷新/重开,全局 unhandledrejection 兜底只兜漏网之鱼。
  • 弹窗主按钮文案:新建=创建、编辑=保存、动作确认=确认+动词(确认下线 / 确认清空);提交即 disabled 防重复提交,失败恢复。危险动作的触发按钮用 .btn.danger / .icon-btn.danger,配套 confirmDialog({danger:true})。
  • 删除 vs 归档的确认分级:删除 / 清空 / 强制下线 = 破坏性 → confirmDialog({danger:true}) + 红色触发钮;归档 / 恢复 = 可逆 → 直接切换 + toast(自研项目、每周工作、人员花名册均如此)。唯一例外:定制项目归档要确认(warn 级,不带 danger)——归档会把它从财务统计与下单/验收口径里摘除,影响数字,值得一次停留。
  • 关键字搜索全应用一个行为:页内搜索框(bindKeyword)与顶栏全局搜索同为 320ms 防抖实时查询,共用 state.keyword,不再区分回车/实时两套。列表卡头「共 N 条」一律取过滤后条数,与分页器一致。
  • 归档过滤统一:自研产品 / 重点工作 / 定制项目用「含归档」switch 开关(state.showArchived / focusArchived / customArchived=false|all),人员花名册用三态下拉(在用 / 已归档 / 全部,导出跟随同一状态)。

备注:历史遗留的 .pcard、.board-grid、.svg-chart、.legend、.risk-item 等零引用样式已随死代码清理删除(2026-10-29)。

数据导出

各列表页右上角均有 导出 Excel,导出内容会带上页面当前的筛选条件:

位置 导出内容 接口
定制项目 定制项目明细(含区域、金额、进度、收入确认、入库时间、备注 + 合计行) GET /api/export/custom
定制项目 定制项目周期记录(「项目总览」工具条「导出周期记录」,按顶栏所选周期 / 月份) GET /api/export/custom-updates
项目管理 项目管理清单(跟随页面全部筛选:分类 / 关键字 / 负责人 / 只看未更新(+顶栏周期) / 归档) GET /api/export/projects
工作看板 本周期(或本月)的执行记录明细(工具栏「导出 Excel」;跟随顶栏周期与搜索框关键字,不受负责人筛选影响) GET /api/export/updates
每周工作 重点工作清单(工作内容 / 说明 / 预计完成时间 / 录入周 / 执行状态 / 是否延期 / 结果反馈 / 更新) GET /api/export/focus
人力资源库 花名册(跟随小组 / 关键字 / 归档筛选;含在管 / 定制项目数、合同额、待计收) GET /api/export/staff

导出的 xlsx 带表头样式、冻结首行、自动筛选,金额列按千分位格式;文件名含导出日期。

财务统计口径

定制项目的金额统计全部收敛在 app/finance.py,页面、工作看板、导出都从它取数,不存在第二套算法。

口径 认定方式
已下单 只看项目归属:origin ∈ {华智下单, 存量项目, 汇智直签};提前交付 不算下单
下单归属季度 / 年度 sign_date 的 YYYY-MM 前缀;认不出年份的计入 kpi.sign_unknown,页面上提示补录
验收归属季度 / 年度 只认 accept_year + accept_date(Q1~Q4);accept_date_real 已停用,不再参与统计
未分季 认得出年份、认不出季度的行(sign_date 残缺成「2024/」、或只有 accept_year 没有 accept_date):计入年度,年度任务表里单列「未分季」一行
计收 累计看主档 revenue_amount;本周期新增看 custom_updates.revenue_delta 之和
金额单位 项目金额一律 元;年度计收目标一律 万元(wanVal() 录入时换算,接口按字段名区分)
  • 统计范围跟顶栏周期走:?period_id= 看一周,?year=&month= 看一月,季度由月份自动归(quarter_of_month)。 跨季度、跨年度只以 context.year / context.quarter 为准,不会因为库里存在别的年份就串到别的季度去。
  • 年度计收目标(GET|PUT /api/custom/annual-targets?year=):存过就以库里为准,某季度清空即 0; 完全没配过的年份才回落到 constants.CUSTOM_ANNUAL_TARGETS_DEFAULT。目标值写非数字返回 400。
  • 验收年度与季度成对校验:只给其中一个 → 400,避免出现「有 Q3 没年份」这种没法归类的行。
  • 年度任务表的不变式:四个季度 + 未分季 = 合计 = KPI 年度(下单、验收两条口径都成立)。 历史库里确实有「有年份没季度」的行,早期版本会让它们从季度表里静默消失, 于是同一屏上「合计」比 KPI 年度少一笔;现在单列一行,既不丢数也不硬塞进某个季度。 annual.unscheduled 给出笔数与金额,kpi.sign_no_quarter / kpi.accept_no_quarter 是计数。
  • 周期记录里的 amount_delta / revenue_delta 是增量,会同步落到项目主档: 新建记录 → 主档累加;修改记录 → 按新旧差额回补;删除记录 → 一并扣回。 AI 写入时「parsed 给了 amount 绝对值就用绝对值,否则累加明细增量」,两条路只走一条,不会重复计。
  • 历史数据可疑时执行 finance.backfill(db)(幂等,可反复跑):按上面的口径重算验收年份与商务阶段。

收入确认口径

定制项目按完工百分比法确认收入:

阶段 确认比例
商机/报备 0%
已签单/下单 10%
开发中 10% + 40% × 开发进度
交付完成 70%
已验收 90%
已计收 100%
暂停/异常 30%
已关闭 100%
  • 可确认收入 = 合同额 × 上表比例
  • 待计收 = 可确认收入 − 已计收
  • 待开票 = 合同额 − 已开票、待回款 = 合同额 − 已回款(均不小于 0,随开票 / 回款金额自动更新)
  • 开票与回款金额在项目详情抽屉、定制项目详情抽屉、工作看板右栏都能直接填
  • 项目上可填「手动确认比例」覆盖阶段推算(用于预付、分批收款等特殊情形)
  • 比例定义见 app/constants.py::CUSTOM_STAGES 与 custom_revenue_ratio(),改一处即可全局生效

数据模型

# 项目管理(长期重点项目)
Period(周期: 一行=一个自然周, kind 恒为 week——月粒度由 year/month 列合成, sort_key 全排序)
   └── Project(分类, 负责人 owners[0], 其他负责人, 团队成员, 状态, 重点标记, 进度, 标签)
          ├── Task(子任务)
          └── Update(执行情况: 正文, 摘要, 进度, 状态, 风险, 下一步, 来源, 原文)

# 定制项目(独立)
CustomProject(名称, 客户, 区域, 合同额, 阶段, 开发进度, 手动确认比例,
              已计收金额, 交付负责人(单人), 团队成员, 入库/签单/交付/验收/计收日期, 开票/回款金额, 重点, 归档)
              # 定制项目不做多负责人:other_owners 列保留在库里但不再读写
   └── CustomUpdate(周期, 阶段, 内容, 进度, 本期新增下单, 本期新增计收, 风险, 下一步)

# 每周工作(独立:条目不是项目,不挂子任务与执行记录)
WeeklyFocus(工作内容, 说明, 录入周→Period, 预计完成时间, 执行状态, 是否延期, 结果反馈, 归档)

Staff(姓名, 归属小组, 人员归属, 说明, 排序, 归档)   # 花名册:所有「负责人 / 团队成员」下拉的唯一来源
Category / Tag / Setting(AI 配置、年度计收目标 custom_annual_targets:{年份}) / ImportLog(AI 整理留痕)

# 权限(RBAC)
Role(名称, 说明, is_builtin) ── RoleMenu(菜单, 级别 ro|rw)      # 授权矩阵:角色 × 菜单
User(姓名, 账号, 口令散列+盐, 是否启用, 最近登录) ── UserRole(用户, 角色)   # 多角色,权限取并集取高
UserSession(token, 用户, 过期时间, IP, UA)                      # 会话,可按角色/账号吊销
AuditLog(用户, 动作 create|update|delete|login|logout|deny, 菜单, 方法, 路径, 状态码, IP, 详情)

列级对齐(唯一的迁移通道,没有 alembic):启动时 schema_patch.ensure_columns 给老库补模型新增的可空列; 模型删掉的死列由 schema_patch.drop_stale_columns 按 STALE_COLUMNS 白名单定点 DROP(SQLite ≥ 3.35)。 删「带 Python default 的 NOT NULL 列」必须登记白名单——不删掉老库里的残留列,INSERT 会直接撞 NOT NULL 约束。 新增死列清理一律走白名单,不做「模型没有就删」的全量对账。

原表映射关系:

  • 周工作情况总结:时间 → Period;工作内容 → Project;内容说明 → Task;完成情况 → Update (三列均为稀疏填充,导入时逐级向下继承;仅填「完成情况」的行作为上一条记录的续行合并)
  • 原「定制开发」的 92 个子任务 → custom_projects(名称尾部的金额如「(39,400.00)」会被解析成合同额)
  • 项目明细表 39 条台账 → custom_projects(区域 / 金额 / 类别→阶段 / 状态说明),与子任务同名时自动合并

AI 整理

两套体系各有独立提示词:

  • 项目管理(常规执行记录):抽取 摘要 / 进度 / 状态 / 子任务列表 / 风险 / 下一步

  • 定制项目类:抽取 商务阶段 / 开发进度 / 合同额 / 累计计收 / 本期新增计收 / 摘要 / 风险 / 下一步 / 本期明细

  • 每周工作条目不过 AI:在独立面板里直接填(工作内容 / 说明 / 预计完成时间填日历日期 / 执行状态)

  • 默认走 OpenAI 兼容协议,支持 DeepSeek、通义千问(兼容模式)、Moonshot、智谱、OpenAI、本地 Ollama 等。

    • Ollama 示例:Base URL http://localhost:11434/v1,模型 qwen2.5:14b,Key 任意填。
  • 未配置 API Key 时自动降级为本地规则解析:按编号切分事项、正则提取百分比与金额、 关键词判定阶段 —— 无需 Key 也能完成录入。

    • 阶段判定做了特殊处理:文本里同时出现「已计收」和「进度 60%」时判为开发中,计收金额由 revenue_delta 承载。
  • 解析结果写入前始终提供可编辑预览,确认后才落库,并留痕到 import_logs。

测试

./.venv/bin/pip install -r requirements-dev.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
./.venv/bin/python -m pytest              # 103 个用例,几秒钟跑完
  • 测试跑在临时库里:tests/conftest.py 在 import 业务模块之前就把 DATABASE_URL 指向临时文件,不会碰 data/board.db。
  • 每个用例重建表结构并重新补种内置角色与管理员,用例之间互不污染;AI_API_KEY 置空, AI 相关用例走确定性的本地规则解析,不联网。
  • 覆盖范围:登录 / 口令 / 会话限流、RBAC 授权矩阵与越权与审计、周期与项目与执行记录、 定制项目财务口径(跨季度、跨年回归)、年度目标、花名册 / 每周重点 / 工作看板、AI 整理与六类 Excel 导出。
  • 还有一道静态防线:tests/test_api_contract.py::test_前端查询参数必须在后端有声明 扫描 web/src/api/endpoints.ts, 前端发出的每个查询键 / body 键都必须在后端 OpenAPI 里声明过(旧版抓到过「前端一直发、后端一直丢」的整类 bug)。

迁移到 MySQL

  1. 安装驱动:pip install pymysql cryptography
  2. 修改 .env:
    DATABASE_URL=mysql+pymysql://user:password@127.0.0.1:3306/unis_board?charset=utf8mb4
    
  3. 重启服务(表结构自动创建)。全新库如果要从旧 Excel 还原历史数据,再依次执行 scripts/import_excel.py --reset 与 scripts/legacy/migrate_custom.py。

数据访问层全部使用 SQLAlchemy ORM,无原生 SQL、无 SQLite 专有语法,切换方言无需改业务代码。

目录结构

app/
  main.py            FastAPI 入口(API 挂载在 /api,静态页面在 /)
  config.py          配置与 .env 加载(DATABASE_URL、AI 参数、SESSION_DAYS)
  db.py              engine / Session(按 URL 自动适配方言)
  models.py          ORM 模型(项目 + 定制项目 + 每周工作 + 花名册 + RBAC)
  constants.py       状态/阶段常量、收入确认比例、区域与阶段识别、权限菜单目录
  security.py        口令散列、会话、权限解析与路由依赖(RBAC 的门)
  audit.py           操作审计写入
  finance.py         定制项目财务口径唯一入口(下单/验收归属、年度目标、回填)
  export.py          xlsx 生成(表头样式、冻结、筛选、金额千分位)
  ai_parser.py       LLM 解析 + 本地规则兜底(通用 / 定制两套)
  routers/           auth · rbac(角色/账号/会话/审计) · board(周期/元数据) · weekly(看板数据) ·
                     projects · custom(定制项目 + 财务) · focus · staff · ai · export
web/                 前端(nex.config.yaml 标准栈:React + TypeScript + Vite + Ant Design +
                      Tailwind v4 + Zustand + React Router + Axios)
   src/
     main.tsx App.tsx router.tsx    入口 / 会话门 / 八个视图的懒加载路由
     api/          client.ts(Axios:401 广播、中文错误、导出走 blob+下载)
                   endpoints.ts(一接口一函数,查询键集中在这一层,测试据此对表)
     store/        session.ts(登录态与 canR/canW)· meta.ts(字典/周期/台账缓存 + dataRev)
                   ui.ts(界面状态,sessionStorage 键 unis.ui.v2,字段与旧版一致)
     components/   Shell(侧栏/顶栏/用户胶囊)· PageHead · PanelCard · KpiCard · DataState ·
                   PagerBar · Trunc · PeriodPicker · LoginGate · ProfileModal · UserChip
     domain/       ink.ts(界面色只引用 token)· pills.tsx(状态标签:一个 --c 派生底色)
     icons/        唯一图标层:SVG 路径表 + <Icon/> / <IconBadge/>(AntD 自带图标不参与业务用图)
     styles/       tokens.css(设计 token 唯一来源 + Tailwind @theme)· app.css(结构层)
     views/        board · projects · custom · focus · staff · intake · settings · rbac
   index.html · vite.config.ts · tsconfig.json · package.json · package-lock.json
   dist/           Vite 构建产物(不入库,由 FastAPI 挂在 / 与 /static 下)
   legacy/         改造前的零构建版(app.js · styles.css · icons.js · index.html),没有 dist 时兜底
tests/               pytest 接口测试(conftest 用临时库,绝不碰 data/board.db)
scripts/
  run.sh             本地启动:Python / venv / 依赖 / .env / 建库自动兜底
  deploy.sh          Docker 部署命令封装:up / update / restart / down / logs / status / backup / mirror
  init_db.py         建表 + 预置分类(启动时幂等)
  import_excel.py    历史 Excel(周工作情况总结 / 项目明细表)导入
  import_staff.py    人员名单导入
  import_custom_ledger.py  定开项目市场台账导入
  legacy/            一次性历史修数脚本(shift_year · merge_project · migrate_custom ·
                     add_entry_date · fix_period_split),不参与启动流程
data/board.db        SQLite 数据库
Dockerfile           两阶段镜像:node:22 构建 web/dist → python:3.12 运行(启动时自动补表/预置分类)
docker-compose.yml   部署编排(./data 持久化、HOST_PORT、健康检查)
.dockerignore        排除 data/ 与 .env,不把数据和密钥打进镜像

API 速览

鉴权走 HttpOnly Cookie unis_session(由 /api/auth/login 下发,只认 Cookie,不认自定义头); 除 /api/auth/login 与 /health 外,所有接口都要求已登录,否则 401。 写操作(POST/PATCH/PUT/DELETE)额外要求对应菜单是 rw,越权返回 403 并留审计。 请求体约定:新建实体用 Pydantic 模型(XxxIn,校验失败 422 中文提示); 部分更新(定制项目、定制交付记录、人员、设置的 PATCH/PUT)收自由 JSON + 后端字段白名单 (payload: dict:只更新带来的键、不认识的键忽略),加字段只改白名单一处,两种模式不要混用。

# 登录与自助
POST /api/auth/login                 {username,password} → 当前用户;会话 token 只写在 Set-Cookie 里
POST /api/auth/logout                吊销当前会话
GET  /api/auth/me                    当前账号 + 角色 + 菜单权限表(前端据此渲染侧栏)
PUT  /api/auth/me                    改自己的姓名
POST /api/auth/password              改自己的密码(改完踢掉其它会话)

# 权限管理
GET  /api/rbac/meta                  菜单目录 + 级别字典 + 内置角色
GET|POST /api/rbac/roles             角色清单(含授权矩阵)/ 新建角色
PATCH|DELETE /api/rbac/roles/{id}    改名称、说明、menus({菜单: ro|rw});改授权会踢掉该角色的会话
GET|POST /api/rbac/users             账号清单 / 新建账号(role_ids 分配角色)
PATCH|DELETE /api/rbac/users/{id}    改资料、启停、重设密码;停用即吊销会话
POST /api/rbac/users/{id}/revoke     只吊销某个账号的全部会话
GET  /api/rbac/sessions              在线会话(用户、IP、UA、到期、token 摘要)
DELETE /api/rbac/sessions/{token}    吊销单个会话
GET|DELETE /api/rbac/logs            操作审计(服务端分页)?username=&menu=&action=&days=&limit=&offset=;返回 {total, items}
                                     / DELETE 按 days 清理

# 通用
GET  /api/meta                       状态字典 / 菜单 / AI 配置状态
GET  /api/periods                    周列表 + 按月聚合(today_id = 今天所在的周,顶栏默认落它;没有会自动补建)
POST /api/periods                    新增周期(传 label 如「9月第1周」,年份自动接续;重复提交返回已有的)
DELETE /api/periods/{id}             删除空周期(有记录则拒绝)
GET  /api/weekly?period_id=|year&month&owner=&all_custom=
                                     工作看板:重点项目 + 定制项目本周动态 + KPI
                                     (行上带 is_new / updated_this_period / idle_weeks / worst_status;
                                       非重点且本周无记录的默认不列出,all_custom=true 才列出在途定制;
                                       没有任何周期时返回全键 0 值骨架,前端不用兜底)
GET  /api/projects                   (?archived=false|true|all&category_id=&is_key=&keyword=&owner=&period_id=|year&month)
POST /api/projects   PATCH|DELETE /api/projects/{id}
                                     (owners/members 传人名数组,整体替换:不传=不改,传 []=清空;owners[0] 回写 owner 列)
GET|POST /api/categories             PATCH|DELETE /api/categories/{id}
GET  /api/updates?project_id=&period_id=|year&month&limit=
                                     标签与子任务没有独立端点:标签随 POST|PATCH /api/projects 的 tags 数组
                                     自动创建 / 复用;子任务随 POST /api/updates 的 task_name 自动创建 / 复用
                                     周期执行记录(月粒度含该月各周;范围内没有周期就返回空,不回落到最新周)
POST /api/updates                    写入口校验:项目/周期必须存在、状态合法、正文与摘要不能都空
PATCH|DELETE /api/updates/{id}

# 定制项目
GET  /api/custom/meta                阶段字典 + 区域列表 + 交付环节(pipeline) + 卡点阈值(aging_days)
GET  /api/custom/projects?stage=&region=&keyword=&archived=&owner=
POST /api/custom/projects            PATCH|DELETE /api/custom/projects/{id}
                                     (owner 是单个人名;members 传人名数组整体替换;不再接受 owners,多负责人只属于重点项目)
POST /api/custom/updates             PATCH|DELETE /api/custom/updates/{id}
                                     (amount_delta / revenue_delta 是增量,会自动累加/回补主档金额,见「财务统计口径」)
GET  /api/custom/finance?period_id=|year&month
                                     财务汇总:context(年/月/季度区间) + kpi(下单、季度与年度验收、计收…) + 年度任务表
GET|PUT /api/custom/annual-targets?year=   年度计收目标(万元)。存过就以库里为准,非数字返回 400

# AI 整理(两套体系各自独立;未配 Key 自动降级为本地规则解析)
POST /api/ai/parse                   粘贴原文 → 结构化预览。**只读**:写了新项目名也不会建项目
POST /api/ai/commit                  确认写入:按 tasks 建子任务与执行记录(同名子任务复用),回写主档,留痕 import_logs
POST /api/custom/ai/parse            定制版预览(阶段/合同额/本期计收/本期明细)
POST /api/custom/ai/commit           定制版写入:按名称自动建档,绝对值优先、否则累加明细增量

# 每周工作(重点工作)
GET  /api/focus?archived=false|true|all&status=&keyword=
                                     条目清单(period_id / period_label 都是**录入周**,分堆由调用方判定)
POST /api/focus                      工作内容非空;period_id=录入周(前端传顶栏当前周,不传按今天所在的周补)
PATCH|DELETE /api/focus/{id}         改 due_date 不会搬走归属周

# 人力资源库
GET  /api/staff?archived=false|true|all&group=&keyword=
                                     花名册 + 各自负载(在管/重点/定制数、定制合同额、待计收)+ 花名册外负责人 + 小组与归属字典
POST /api/staff                      PATCH|DELETE /api/staff/{id}
                                     (姓名与花名册重名返回 400;名下有项目时禁止直接删除,提示先归档,?force=true 才强制删;
                                       改名会把项目与定制项目上的负责人一起同步,返回值 synced 说明同步了几条)

# 其他
GET|PUT /api/settings                AI 配置等(GET 需 settings 只读,PUT 需可编辑)

# 导出(均返回 xlsx,筛选口径与页面对应)
GET  /api/export/custom              ?region=&origin=&status=&risk=&accept_plan=&keyword=&archived=false|true|all(末尾带合计行)
GET  /api/export/custom-updates      ?period_id=|year&month&keyword=
GET  /api/export/projects            ?category_id=&keyword=&owner=&idle_only=1&period_id=|year&month&archived=false|true|all(默认 false 与页面一致;owner 匹配主/其他负责人;idle_only 需带周期;搜归档记得 archived=all)
GET  /api/export/updates             ?period_id=|year&month&project_id=&keyword=(匹配内容/摘要/子任务/项目名)
GET  /api/export/staff               ?archived=false|true|all&group=&keyword=
GET  /api/export/focus               ?archived=false|true|all&status=&keyword=
                                     导出与接口的差别:范围解析不出周期时导出给全量(让人把数据带走),
                                     接口则返回空(避免把「没数据」看成「全周期数据」)