|
|
||
|---|---|---|
| .workbuddy/memory | ||
| app | ||
| scripts | ||
| tests | ||
| web | ||
| .dockerignore | ||
| .env | ||
| .env.example | ||
| .gitignore | ||
| Dockerfile | ||
| README.md | ||
| deploy.sh | ||
| docker-compose.yml | ||
| pytest.ini | ||
| requirements-dev.txt | ||
| requirements.txt | ||
| run.sh | ||
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/shift_year.py --dry-run # 先预演,看清楚了再执行
python scripts/shift_year.py # 全部 +1 年
python scripts/shift_year.py --years -1 # 反向回滚
内部按年份从大到小更新,避免 2024→2025 撞上尚未更新的 2025;执行后会校验 sort_key 无重复,有重复则整体回滚。 执行前建议手动备份:
cp data/board.db data/board.db.bak
快速开始
cd /Users/jiliu/WorkSpace/unis_manager
./run.sh
首次运行 run.sh 会自动完成:选择带依赖的 Python 解释器 → 缺依赖则安装 → 建库 → 导入历史 Excel → 拆分定制项目,然后启动并打开浏览器。
启动方式与排错
| 场景 | 命令 |
|---|---|
| 正常启动 | ./run.sh |
报 permission denied |
chmod +x run.sh 后重试(不要用 sudo) |
| 不想改权限 | bash run.sh |
| 换端口 | PORT=8771 ./run.sh |
| 关闭热加载 | DEV=0 ./run.sh(默认是开着的) |
| 不自动开浏览器 | NO_OPEN=1 ./run.sh |
| 提示"端口已被占用" | 原窗口 Ctrl+C,或 lsof -ti:8770 | xargs kill 后重跑 |
| 用 Docker 部署(不装 Python) | ./deploy.sh up,见下面「Docker 部署」 |
⚠️ 不要用
sudo启动:数据库文件会变成 root 属主,后续写入会失败。
热更新(默认开启):uvicorn 除
*.py外还会监听web/**的 js/css/html 与.env,改动即重启; 页面里的web/livereload.js每秒读一次/health的启动代际,发现服务重启后自动刷新浏览器。 也就是说改完代码不用手动重启、也不用手动刷新。DEV=0 ./run.sh可关掉(关闭后该脚本首轮即自行停止)。data/*.db的写入不会触发重启。
手动分步执行(等价于 run.sh 干的事)
pip install -r requirements.txt
python scripts/init_db.py
python scripts/import_excel.py "/Users/jiliu/WorkSpace/定开管理/软件开发部管理工作执行表.xlsx"
python scripts/migrate_custom.py
python -m uvicorn app.main:app --port 8770
重新导入:
python scripts/import_excel.py <xlsx> --reset之后再跑一次python scripts/migrate_custom.py(迁移脚本会删除常规表里的「定制开发」容器,重复执行前请先 reset)
Docker 部署(换机器 / 上服务器)
不想装 Python,或者要放到服务器上常开,用 Docker:
cd /path/to/unis_manager
./deploy.sh up # 构建镜像 + 后台启动 + 等健康检查
打开 http://127.0.0.1:8770。首次启动自动建表、预置分类,并创建内置角色与 admin 账号(密码见 .env)。
| 文件 | 作用 |
|---|---|
Dockerfile |
运行镜像:装依赖 + 拷 app/ web/ scripts/;启动时先跑 init_db.py(幂等)再起 uvicorn |
docker-compose.yml |
编排:./data 挂进容器存数据库、HOST_PORT 控对外端口、restart: unless-stopped 随 Docker 自启 |
deploy.sh |
命令封装:up / update / restart / down / logs / status / backup / mirror,顺带检查 docker 是否在跑、.env 与 data/ 是否存在,并在构建前定好基础镜像与 pip 源 |
.dockerignore |
保证 data/、.env、.git 不会被烤进镜像 |
| 场景 | 命令 |
|---|---|
| 改完代码上线 | ./deploy.sh update(重建镜像并替换容器) |
改了 .env(AI Key / 端口) |
./deploy.sh restart |
| 看日志排错 | ./deploy.sh logs |
| 看状态与健康检查 | ./deploy.sh status |
| 停止(数据保留) | ./deploy.sh down |
| 换对外端口 | .env 里 HOST_PORT=8080,再 ./deploy.sh up |
| 裸 compose 命令 | docker compose up -d --build / docker compose down |
| 构建时基础镜像 / pip 下载超时 | ./deploy.sh mirror 重探,或手工指定 PIP_INDEX_URL=... BASE_IMAGE=... ./deploy.sh up(见下「国内网络加速」) |
| 把现有数据带到新机器 | ./deploy.sh backup → 拷到目标机 data/board.db → ./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(清华 / 阿里 / 腾讯) |
./deploy.sh up 构建前把这两道都定下来,原则是能本地解决就不联网:
- 基础镜像只看本地有没有:
BASE_IMAGE指定的镜像在本地 → 直接用;只有同名 tag(如python:3.12-slim)→ 也用(仓库前缀只是当初从哪儿拉的,镜像是同一份)。本地确实没有才试拉一次(守护进程配的 registry-mirrors 在这一步生效),还拉不到就直接报错停下并打印补救命令——不去逐个试加速站,那种循环只会白等几分钟。 - pip 源:在构建用的容器里真
urlopen一次逐个试(容器网络 = 构建网络,比宿主机 curl 准),默认清华源。 - 定下来的值只 export 给本次构建,不写回
.env(.env在 git 里,把某台机器的地址带到另一台机器正是故障源)。
./deploy.sh up # 定源(本地有镜像就不联网)→ 构建 → 等健康检查
./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 ./deploy.sh up跳过 pip 探测,源完全由.env说了算。 - 目标机完全不能上网:走离线路。
docker save -o unis-board.tar unis-board:latest→ 拷过去docker load -i unis-board.tar→NO_BUILD=1 ./deploy.sh up(跳过构建直接用本地镜像)。 - 构建失败时脚本会自己打印一份排查清单(
deploy.sh的build_hint),照抄命令即可。
几个坑:
- 数据只落在
./data:重建镜像、down再up都不动数据;备份依旧是拷走data/board.db。 - 时区必须设:容器默认 UTC,而周期/周次/入库时间都按本地日期算,所以 compose 固定传
TZ=Asia/Shanghai,别删。 - 容器内端口固定 8770:
.env的PORT是本机run.sh用的,compose 里覆盖成 8770;要换端口只改HOST_PORT。 - 别和
run.sh同时跑:一是 SQLite 是文件库,同一份board.db不要同时被本机进程和容器读写;二是本机进程绑的是127.0.0.1:8770,比 Docker 发布的*:8770更精确,浏览器和curl 127.0.0.1:8770会全打到本机服务上(症状:/health里dev是true,而容器是false)。两者要共存就给容器换端口:HOST_PORT=8899 ./deploy.sh up。 - 换 MySQL:放开
Dockerfile里pymysql那行重新 build,再把.env的DATABASE_URL指过去(见「迁移到 MySQL」)。
带着现有数据部署
镜像里故意不含数据(.dockerignore 排除了 data/),容器读的是宿主机挂载进来的 ./data/board.db,所以:
- 就在本机这个目录部署 → 什么都不用做,
./deploy.sh up起来读的就是当前这份库;连user_sessions里的登录态都延续,别人不用重新登录。 - 换一台机器部署 → 先把数据取出来,落到目标机的
./data/board.db:
./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 && ./deploy.sh up'
data/board.db本身在 git 里,git clone也会带一份,但那是最后一次提交的状态;要「当前最新」请用./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 期趋势;定制项目入口 → 本周动态总览(顶部标签:本周新增 / 本周验收 / 有交付动态 / 合同额合计 / 本期计收,下面分「本周新增」「本周验收」「本周有变化」三段,每条带阶段、负责人、金额、本期计收与摘要),点某一条再下钻到该项目 → 交付环节五段条 / 财务跟踪四联卡 + 开票·回款行内输入 / 本期交付记录 / 更早的交付记录,改开票、回款、环节日期即时保存(改日期会自动推进商务阶段);每周重点工作 → 只读的说明与状态,要改点「修改」开抽屉 |
| 工具栏 | 「负责人」筛选、「导出本周期记录」,提示里带本期项目数与定制动态数;顶栏可切周 / 月视图(月视图自动汇总该月所有周)。「列入全部在途」开关(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/merge_project.py --from "智空无人机平台" --to "智飞无人机平台" --dry-run
python scripts/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> # 指定别的文件;首次运行 ./run.sh 会自动导入
负责人下拉(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/add_entry_date.py --dry-run # 预演
python scripts/add_entry_date.py # 回填(跳过已有值)
python scripts/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这类只要求登录,不看菜单,否则无法登录与自助改密。 - 内置角色:
管理员(全部rw)、部门成员(业务菜单rw,设置与权限只读/无)、只读访客(除权限外全部ro),is_builtin标记,不能删除。 - 不会被锁死:系统始终保证至少有一个「启用 + 权限管理可编辑」的账号;
一个都没有时
security.ensure_seed会把「管理员」角色补给最早的账号并在启动日志里提示。 - 改权限即踢会话:改角色授权 → 踢掉该角色下所有账号的会话;改/停账号 → 踢掉该账号的会话。 旧 token 不会继续带着旧权限跑。
- 会话:登录发 32 位随机 token,存
user_sessions(有效期SESSION_DAYS,默认 30 天), 只通过HttpOnlyCookieunis_session下发(JS 读不到,前端不存 token); 权限管理页可查看全部在线会话并单独吊销。 - 操作审计:写操作与登录 / 登出 / 越权都落
audit_logs(谁、什么时间、哪个菜单、什么动作、返回码、IP), 权限管理页可按菜单、动作、天数筛选。 - 首个管理员账号来自
.env的ADMIN_USERNAME/ADMIN_PASSWORD(默认admin/admin123,登录后请立刻改密码)。
界面设计语言
前端是零构建的原生 JS(web/index.html + web/styles.css + web/app.js + web/icons.js),设计口径固定如下,新增页面请沿用:
- 禁用「彩色描边」:卡片、列表、步骤条、表格一律中性灰边框(
--border/--border-strong)或无边框,不用圆角多色边框表达状态。 - 重点色只出现在三处:图标、关键数字/文本、小面积 tinted 底板(
.ic-badge、.tag-mini、.kpi.accent-*)。状态色(statusMeta)与阶段色(stageMeta)是唯一配色来源,避免各页面自己调色。 - 图标系统:
web/icons.js内置 50 个 24×24 线性 SVG,stroke=currentColor,颜色跟着文字走。对外 API:svg(name)裸图标;badge(name)图标 + tinted 底板(KPI 用);status()/stage()/pipe()按状态·阶段·交付环节取图标;nameOfStatus()/nameOfStage()/statusBadge()出文案与徽标;hydrate()填[data-icon];auto()自动补前导图标;names()列全部图标名。 - 自动图标:
auto()+MutationObserver在每次渲染后按标题关键词给.card-head h4/.sec-title/.kcol-title/.wk-group-head/.notice/.empty加前导图标,并填充[data-icon];用data-ico属性防重复,标题里自带<svg class="ic">(如阶段看板按阶段取图标)时跳过自动补图,不会出现两个图标。新增区块只要标题里带对应关键词就自动带图标,不用手写。 - 阶段看板列头不带色条:列头用
Ico.stage(code)+--c注入阶段色(.kcol-title .ic { color: var(--c) }),早期那种border-top:3px solid 阶段色的彩条已去掉。 - 交付环节图标按
code取:后端CUSTOM_PIPELINE下发的字段是code(不是key),前端一律Ico.pipe(s.code);写成s.key会静默退化成通用圆点。 - 表格防竖排:
table.tbl th/.pill/.tag-mini统一white-space:nowrap,容易挤窄的列(区域、负责人)在<td>上加class="nowrap";实在挤不下交给.tbl-wrap { overflow:auto }横向滚动。 - 抽屉不被内容撑破:
.form-row > div { min-width: 0 }(grid 子项默认min-width:auto,会被交付环节步骤条撑出整表横向滚动),步骤条本身flex:1 1 132px(132px = 日期输入框含日历图标的最小可用宽度)。
备注:
styles.css里的.pcard、.board-grid当前没有任何 JS 引用(历史遗留样式),此处只做记录,未删除。
数据导出
各列表页右上角均有 导出 Excel,导出内容会带上页面当前的筛选条件:
| 位置 | 导出内容 | 接口 |
|---|---|---|
| 定制项目 | 定制项目明细(含区域、金额、进度、收入确认、入库时间、备注 + 合计行) | GET /api/export/custom |
| 定制项目 | 定制项目周期记录 | GET /api/export/custom-updates |
| 项目管理 | 项目管理清单(分类、负责人、状态、标签、子任务数等) | GET /api/export/projects |
| 工作看板 | 本周期(或本月)的执行记录明细 | 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(周期: 年/月/周, sort_key)
└── Project(分类, 负责人 owners[0], 其他负责人, 团队成员, 状态, 优先级, 重点标记, 进度, 标签)
├── Task(子任务)
└── Update(执行情况: 正文, 摘要, 进度, 状态, 风险, 下一步, 来源, 原文)
# 定制项目(独立)
CustomProject(名称, 客户, 区域, 合同额, 阶段, 开发进度, 手动确认比例,
已计收金额, 交付负责人(单人), 团队成员, 入库/签单/交付/验收/计收日期, 开票/回款金额, 重点, 归档)
# 定制项目不做多负责人:other_owners 列保留在库里但不再读写
└── CustomUpdate(周期, 阶段, 内容, 进度, 本期新增下单, 本期新增计收, 风险, 下一步)
# 每周重点工作(独立:条目不是项目,不挂子任务与执行记录)
WeeklyFocus(工作内容, 说明, 录入周→Period, 预计完成时间, 执行状态, 是否延期, 结果反馈, 归档)
Staff(姓名, 归属小组, 人员归属, 说明, 排序, 归档) # 花名册:所有「负责人 / 团队成员」下拉的唯一来源
Category / Tag / Setting(AI 配置、年度计收目标 custom_annual_targets:{年份}) / ImportLog(AI 整理留痕)
LedgerItem(客户项目台账) # 只剩模型与 Excel 导入解析,界面无入口、接口已下线
# 权限(RBAC)
Role(名称, 说明, is_builtin) ── RoleMenu(菜单, 级别 ro|rw) # 授权矩阵:角色 × 菜单
User(姓名, 账号, 口令散列+盐, 是否启用, 最近登录) ── UserRole(用户, 角色) # 多角色,权限取并集取高
UserSession(token, 用户, 过期时间, IP, UA) # 会话,可按角色/账号吊销
AuditLog(用户, 动作 create|update|delete|login|logout|deny, 菜单, 方法, 路径, 状态码, IP, 详情)
原表映射关系:
周工作情况总结:时间 → 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 任意填。
- Ollama 示例:Base URL
-
未配置 API Key 时自动降级为本地规则解析:按编号切分事项、正则提取百分比与金额、 关键词判定阶段 —— 无需 Key 也能完成录入。
- 阶段判定做了特殊处理:文本里同时出现「已计收」和「进度 60%」时判为开发中,计收金额由
revenue_delta承载。
- 阶段判定做了特殊处理:文本里同时出现「已计收」和「进度 60%」时判为开发中,计收金额由
-
解析结果写入前始终提供可编辑预览,确认后才落库,并留痕到
import_logs。
测试
./.venv/bin/pip install -r requirements-dev.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
./.venv/bin/python -m pytest # 81 个用例,几秒钟跑完
- 测试跑在临时库里:
tests/conftest.py在 import 业务模块之前就把DATABASE_URL指向临时文件,不会碰data/board.db。 - 每个用例重建表结构并重新补种内置角色与管理员,用例之间互不污染;
AI_API_KEY置空, AI 相关用例走确定性的本地规则解析,不联网。 - 覆盖范围:登录 / 口令 / 会话限流、RBAC 授权矩阵与越权与审计、周期与项目与执行记录、 定制项目财务口径(跨季度、跨年回归)、年度目标、花名册 / 每周重点 / 工作看板、AI 整理与六类 Excel 导出。
迁移到 MySQL
- 安装驱动:
pip install pymysql cryptography - 修改
.env:DATABASE_URL=mysql+pymysql://user:password@127.0.0.1:3306/unis_board?charset=utf8mb4 - 重启服务(表结构自动创建),再依次执行
import_excel.py --reset与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/ index.html · styles.css · app.js · icons.js(零依赖,无构建步骤)
tests/ pytest 接口测试(conftest 用临时库,绝不碰 data/board.db)
scripts/ init_db.py · import_excel.py · import_custom_ledger.py · migrate_custom.py · import_staff.py
add_entry_date.py · fix_period_split.py · merge_project.py · shift_year.py
data/board.db SQLite 数据库
Dockerfile 运行镜像(依赖 + 代码,启动时自动补表/预置分类)
docker-compose.yml 部署编排(./data 持久化、HOST_PORT、健康检查)
deploy.sh 部署命令封装:up / update / restart / down / logs / status
.dockerignore 排除 data/ 与 .env,不把数据和密钥打进镜像
API 速览
鉴权走 HttpOnly Cookie unis_session(由 /api/auth/login 下发,只认 Cookie,不认自定义头);
除 /api/auth/login 与 /health 外,所有接口都要求已登录,否则 401。
写操作(POST/PATCH/PUT/DELETE)额外要求对应菜单是 rw,越权返回 403 并留审计。
# 登录与自助
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= / 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|POST /api/tags DELETE /api/tags/{id}
POST /api/tasks 项目子任务
GET /api/updates?project_id=&period_id=|year&month&limit=
周期执行记录(月粒度含该月各周;范围内没有周期就返回空,不回落到最新周)
POST /api/updates 写入口校验:项目/周期必须存在、状态合法、正文与摘要不能都空
PATCH|DELETE /api/updates/{id}
# 定制项目
GET /api/custom/meta 阶段字典 + 区域列表 + 交付环节(pipeline) + 卡点阈值(aging_days)
GET /api/custom/projects?stage=®ion=&keyword=&archived=&key_only=&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 配置等(PUT 需要 settings 可编辑)
# 导出(均返回 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
GET /api/export/projects ?category_id=&keyword=&archived=false|true|all(默认 all)
GET /api/export/updates ?period_id=|year&month&project_id=
GET /api/export/staff ?archived=false|true|all
GET /api/export/focus ?archived=false|true|all&status=&keyword=
导出与接口的差别:范围解析不出周期时导出给全量(让人把数据带走),
接口则返回空(避免把「没数据」看成「全周期数据」)