19 KiB
四算项目管理系统(fourcal-pms)
老四算系统(Spring Boot 1.5 + JPA + Activiti 6 + FreeMarker)的重构版。
- 后端:Python 3.11 · FastAPI · SQLAlchemy 2.0 · MySQL 8
- 前端:Vue 3 · TypeScript · Vite 5 · Tailwind · Pinia(组件体系对齐 sub2api)
- 范围:项目立项(概算)、项目预算、审批流程;配套流程配置、角色权限、 数据权限(支持多套自定义配置)、菜单权限、系统账号、组织架构
- 统一身份:预留 Hub 同步通道(参照 unisoa 的做法,
[hub]开关控制)
快速开始
# 1) 后端(端口 8383)
cd backend
pip install -r requirements.txt
python3 run.py # 首次启动自动建库建表并种基础数据
# 2) 前端(端口 5383,/api 代理到 127.0.0.1:8383)
cd frontend
npm install
npm run dev
打开 http://localhost:5383 ,用 localadmin / admin123 登录。这是本系统唯一的本地账号
(首次登录后请立即改口令):由 seed 维护,每次启动都补,scripts/clean_demo_data.py 也
留着它,清库或重建库都不会把它清没;口令只在本系统校验,从不拿去问统一身份,所以登录页
上验证码那一行可以不填。名字刻意不叫 admin——那个名字留给统一身份里真叫 admin 的人,
否则同步过来只能落成 admin_hubNNN 这种别扭的号。想再留第二把本地门,填
[seed] emergency_account / emergency_password;生产上口令留空(seed 随机生成,只在
启动日志里打印一次)或用 PMS_SEED_ADMIN_PASSWORD 注入,别落进仓库。
演示账号 zhangsan / lisi / wangwu 同一口令,分别对应业务、项目负责人、财务三种角色,
用来验数据权限和审批流转最方便,但只有 [seed] demo_data = true 时才种。它们也是本地账号,
真要按 README 验数据权限,得把这三个名字填进 hub.local_only_accounts,否则会被 Hub 一句
"账号或密码错误"挡在门外。
登录页也收统一身份账号:直接输 Hub 的账号口令(带 Hub 下发的验证码)就能登,
口令归谁验由 hub.login_mode 定,见「统一身份」一节。
验证
cd backend && python3 -m pytest tests -q # 294 passed, 13 skipped
cd backend && python3 scripts/gen_schema.py --check # 建表脚本是否跟模型走样了
cd backend && python3 scripts/clean_demo_data.py # 干跑:看看库里积了多少演示/测试数据
cd frontend && npx vue-tsc --noEmit && npm run build
配置分档
同一个包要在本机、测试机、生产机上跑,三套库三套密钥。办法是给配置文件分档:
config.toml 各环境公共基础值(端口、口令策略、Hub 节奏、上传…;计算口径不在这里)
config.dev.toml 开发/测试档差异(测试库地址口令、JWT 密钥、CORS、种子数据)
config.prod.toml 生产档差异(生产库账号、监听地址、落盘路径;密钥一律留空)
python3 run.py # 默认 dev,读 config.dev.toml
PMS_ENV=prod python3 run.py # 生产档
PMS_CONFIG=/path/x.toml python3 run.py # 只认这一个文件,分档一概不看
- 读两档时做深合并:档位文件只写跟公共值不一样的键,没写的沿用。
- 优先级:环境变量
PMS_*>config.<档位>.toml>config.toml> 内置默认值, 例如PMS_DB_HOST、PMS_DB_PASSWORD、PMS_JWT_SECRET、PMS_HUB_DIRECTORY_KEY。 - 默认档位是
dev,不会因为漏设PMS_ENV而误连生产库。 - 生产把
auto_create_schema设为false,建表交 DBA,用sql/schema.sql。 - 密钥不进仓库:
config.prod.toml里库口令、jwt_secret、Hub 两把 key 一律留空, 由PMS_*环境变量注入;config.dev.toml带的是测试库口令,仓库转公共之前记得挪走。
数据库:开发库 fourcal_pms_dev(本系统自己的库)。
老库 unis_fourcal_dev 作为 legacy 数据源只读挂载,导数与对账用它,不会写入一个字节。
目录
backend/
config.toml / config.dev.toml / config.prod.toml
run.py 启动入口(uvicorn,reload 仅 dev)
app/
config.py 分档配置 + 深合并 + 环境变量覆盖
db.py / security.py / envelope.py / deps.py / seed.py / main.py
dicts.py 数据字典:代码枚举 + 库内维护,一份取值喂到前端
models/ org · permission · project · finance · approval · dictionary(40 张表)
api/ auth · org · system · dicts · projects · finance · approvals(108 个路由)
service/
permissions.py 权限码与菜单树构建
data_scope.py 数据权限引擎(策略表 → SQL 谓词)
biz.py 版本、明细行、计算快照、投影回写
org_sync.py / hub_api.py 统一身份同步
calc/ money · tax · profit · fund_plan · validate · mapping · engine
approval/ candidates · flow · engine
tests/ test_calc(口径)+ test_api_flow(主链路)
scripts/migrate_legacy.py 老库只读导入
scripts/clean_demo_data.py 开发库清回初始状态(默认干跑,删前自动备份,可回放)
sql/schema.sql 生产建表脚本
frontend/src/
api/ http.ts(信封拆解 + 令牌静默续期)· index.ts · types.ts
stores/ auth(登录态与权限视图)· dicts(数据字典缓存)· ui · toast
composables/ useAsync · usePagedQuery · useDict(下拉框取字典)
router/ 路由与守卫;菜单由后端下发,前端不抄权限表
components/
common/ DataTable · Select · DictSelect · BaseDialog · ToastHost · Skeleton …(对齐 sub2api)
layout/ AppLayout · AppSidebar · AppHeader · TablePageLayout
project/ ProjectShell · SectionRail · LineEditor · SummaryStrip ·
ProfitLadder · FundPlanTable · ValidationPanel · ApprovalTimeline
approval/ InstanceDetailDrawer
views/ 工作台 · 项目 · 审批中心 · 组织 · 系统管理(含「数据字典」维护页)
docs/
前端布局方案.md 使用方视角的布局设计(含双层页签的前后对比)
数据权限设计.md 策略模型、求值顺序、字段级权限
审批流程设计.md 去 Activiti 后的流程模型与流转语义
计算口径.md 价税、利润阶梯、资金计划、校验规则、已知老口径差异
接口约定
响应信封
// 成功
{ "ok": true, "data": { ... } }
// 失败
{ "ok": false,
"error": { "code": "validation_failed", "message": "送审前还有 2 项校验没有通过",
"detail": { "issues": [ ... ] }, "traceId": "ac366c13a9744451" } }
- 金额全程字符串,前端不
Number().toFixed()大额数字(超过 2^53 会静默丢精度)。 - 比率是百分数本身(13 表示 13%);可能无定义的比率返回
{value, defined, reason}。 wrapper键用驼峰(contractAmount、pageNo);明细行字段用下划线(include_amount), 与数据库列一一对应,导数时不用换算。- 每个响应带
X-Trace-Id,前端 Toast 会显示traceId,报错能直接贴给运维查日志。
主要分组
| 前缀 | 内容 |
|---|---|
/api/health |
健康检查(含数据库连通、当前档位与口径版本) |
/api/v1/bootstrap |
一次拿全:环境、数据字典、菜单树、权限码、字段脱敏配置 |
/api/v1/auth |
登录、刷新、改口令、登出 |
/api/v1/org |
部门树、账号、岗位、accounts/options(人员选择器)、accounts/{id}/roles(给人员配角色)、accounts/roles/batch(批量分配:按勾选或按当前筛选圈人,追加/移除/覆盖,一次上限 500 人)、Hub 同步 |
/api/v1/projects |
项目 CRUD、软删除与回收站恢复、彻底删除、阶段流转、成员与可见角色 |
/api/v1/finance/{module} |
概算/预算:版本、明细行、试算、快照、校验、送审 |
/api/v1/approvals |
待办/已办/我发起/监控、办理、撤回、退回、转办、加签、流程配置 |
/api/v1/system |
角色、数据权限策略与试算解释、权限树、业务参数、计算口径 |
/api/v1/system/operation-logs |
审计查询:写操作日志(含明细与筛选项)、login-logs 登录日志 |
/api/v1/dicts |
数据字典:前端按下拉框编码取值(只要求登录) |
/api/v1/system/dicts |
数据字典维护:字典与取值的增删改、启停、排序、恢复默认 |
明细行的三种写法
POST /finance/budget/projects/{id}/lines/{lineKey} body { "data": {...} } 单行新增/更新
PUT /finance/budget/projects/{id}/lines/{lineKey} body { "rows": [...] } 整段替换(前端批量保存用这个)
DELETE /finance/budget/projects/{id}/lines/{lineKey}/{lineId}
PUT 是整段替换语义:一次提交这一段的全部行。每次落库都触发一次重算,
重算结果写入 calc_snapshot,并把关键指标投影回 project 主表。
设计上的几个决定
biz_revision取代老系统的_temp影子表。 概算/预算的每一版都是一行biz_revision, 所有明细行带revision_id。送审冻结的是版本号,不是复制一份表。- 计算快照是唯一事实。
calc_snapshot.payload_json存完整结果,project表上的利润列只是投影,由biz.apply_projection写入。对账看快照,不看主表。 - 审批去 Activiti。 流程定义/节点/实例/待办/流水五张表,与业务同库同事务。 "这单现在谁在审"变成一次查询。
- 数据权限是策略表,不是角色上的一个字段。 5 种主体 × 10 种范围 × allow/deny × 可嵌套 条件树,能表达"同一个人不同列表不同范围"。详见《数据权限设计》。
- 口径可配置并带版本号。 老系统写死的 2.8% 管理费率、10% 差旅限额、价内税公式、
零分母行为都是
system_config里calc.开头的业务参数,在「系统 → 计算口径」页面上改、 保存即生效,双跑对账时切回老口径复现,version随快照留痕。配置文件里一条计算规则都不留。 - 下拉框取值统一进数据字典。 以前一份枚举写三处:model 的
LABELS、接口里现拼 的[{value,label}]、前端视图里的常量数组——项目类型就因此对不上(接口叫"工程集成类", 列表页写"系统集成"),采购明细的产品归属还给过内核根本不认的编码,选了不报错、钱也不投影。 现在dict_type/dict_item是运行期唯一来源:随/bootstrap下发,页面用DictSelect按编码取值;「系统 → 数据字典」能改名、排序、停用、加自定义字典,保存即生效。 代码那份 LABELS 退成兜底与护栏——内置取值不许改也不许删(业务代码按它判分支), 只在界面上提供"恢复默认"。字典管候选项和展示名,不管校验:能不能送审、走哪条分支 仍然看代码常量,否则改个名字就能把状态机改出洞。 - 前端砍掉了双层页签。 明细表从"页签"降级成"目录",计算结果常驻右手边。 详见《前端布局方案》。
数据迁移
老四算(unis_fourcal_dev,93 张表 / 828 个项目)用 backend/scripts/migrate_legacy.py 导进新库。
这个脚本有三条不可商量的前提:老库只读(连接一开就 START TRANSACTION READ ONLY,脚本里只发
SELECT)、默认干跑(不加 --apply 一律回滚)、不保留老库主键(新库自己发号,老 id→新 id
走内存映射;直接搬会和 seed 出来的 admin、演示项目撞号,撞了是静默覆盖,比报错更糟)。
cd backend
python3 scripts/migrate_legacy.py # 干跑,先看报告
python3 scripts/migrate_legacy.py --apply --steps org,user,role # 只导人头,先验证头寸
python3 scripts/migrate_legacy.py --apply --limit-projects 50 # 前 50 个项目试水
python3 scripts/migrate_legacy.py --apply # 全量
步骤顺序固定为 org → role → positions → user → flow → project → estimate → budget → visible,
--steps 只挑要做哪几步,不会打乱依赖顺序。干跑一次约 3~5 分钟(按项目逐张拉明细,远库往返占大头)。
老库有几处口径和新系统不一样,脚本显式换算并在报告里计数,不静默改数:
| 项目 | 老库 | 新系统 |
|---|---|---|
税率 tax_rate |
小数 0.13 |
百分数 13(只放大 (0,1]) |
利润率 *_margin |
本来就是百分数 12.15 |
原样搬运,不乘 100 |
采购类别 category |
procurement_type 的 id 字符串 "8" |
中文名 + 产品归属编码 huazhi |
日期 pay_time 等 |
datetime / 空 |
DATE 列,空给 NULL(DATE 写 '' 报 1292) |
布尔 is_deleted |
bit(1),回来是 b'\x00' |
bool(b'\x00') 是 True,按非零字节判 |
这两条口径都是实测钉住的,不是猜的:利润率 1578.60 / 12990 = 12.15 与 margin=12.15 对得上,
而库里确实有 0.03 这种利润率——那是 0.03%,早期版本一个 -1 < v < 1 的启发式把它放大成了 3%。
对应的回归测试在 tests/test_migrate_legacy.py。
在途审批和审批历史都不迁。 老流程实例在 Activiti 里,硬迁过来只能造出一堆来路不明的待办;
切流前把在途单子清干净,新送审一律走新流程。已经走完的历史审批想看的话,源数据在老库
act_hi_procinst(2,040 条)/ act_hi_taskinst(9,341 条)/ act_hi_comment(17,419 条),
需要单独做成 approval_record 流水跟新流程解耦——这得先定历史流水在新界面里怎么摆,
脚本里没有开关,别去猜 --with-history。
报告里 需要你确认的 那几条是真要人跟的:老流程候选人只有角色能自动对上(candidate_users 是老库
用户 id,要按新账号重新指定);老库没有垫资年利率字段,按 --advance-rate 统一赋值后要逐个核对;
约一成采购明细的类别落在四个产品归属之外("外购产品""外购服务"这类),product_category 只能留空。
导入完成后到项目里点一次「重新试算」,让计算快照和投影按新口径重算。
字符串超过新库列宽时脚本会截断并计数(报告里 截断:表.列 那几行),列宽从模型元数据现读。
触发了就说明列宽该跟老库对齐——比如 pay_way 老库存的是合同付款条款、实测 136 字,新列就从 64
放到了 255。放着不管等于默认丢数据。
生产建表脚本 backend/sql/schema.sql 由模型编译,别手改:
cd backend && python3 scripts/gen_schema.py # 改完模型重新生成
cd backend && python3 scripts/gen_schema.py --check # 只比对,可挂 CI
统一身份(账号组织同步 + 免登)
按 dsh-hub 对接契约实现,口径与 unisoa 一致:hub 是人员与组织的唯一权威源,本系统只读消费, 不回写、不另建一套人。免登只走一次性票据;登录页那个口令框默认也归 Hub 判, 本系统不自建第二套口令。
[hub]
enabled = true
base_url = "https://hub.oa.unissense.tech"
directory_key = "" # X-Directory-Key:拉组织与人员
app_code = "" # 免登应用编码,用于校验票据受众
integration_key = "" # X-Integration-Key:校验票据
login_mode = "hub" # 口令校验口径:hub / hybrid / local / sso
- 两把密钥互不通用:目录密钥换不了身份,应用密钥读不到目录。同步页把它们分开显示, 因为配错最常见的表现是"同步下来是空的",合并成一个"凭据已配置"会把排查方向带偏。
- 接口路径写死在
HubConfig里(目录/api/v1/auth/directory、增量…/changes、验票/api/v1/auth/tickets/verify,加上登录页要问的/auth/captcha、/auth/login和补主键用的/api/v1/auth/me),不做成可配项:路径是契约的一部分,配错一个斜杠就会 静默同步到空目录,然后按"hub 里没人了"把本地账号全停用。 - 两条节奏:增量按
changes_interval_seconds(建议 45 秒)蹭游标,全量按sync_interval_minutes(默认每日)校对。全量必须留着,因为人员资料微调不产生变更事件。 游标只在整批成功后推进;游标落后于对端最早流水、或收到只带 id 的组织事件时,自动退回全量。 login_mode决定登录页那个口令框收谁的账号、口令归谁验:hub(默认,只问统一身份, 连不上当场回"统一身份暂不可用")/hybrid(连不上才退回本地口令)/local(只用本地口令)/sso(口令登录整个关掉,页面只留"前往统一门户")。逐档差别见文档 §1.1。- Hub 账号在这里没有本地口令。
_verify里不存在"Hub 连不上就当本地账号放行"的兜底——那会让 停用与离职下线在故障期间集体失效;Hub 说"密码不对"也不会再拿库里的旧哈希兜第二层,被拒 同样不去累加本地锁定计数。逃生门是break_glass_login,只放行source=local的本地账号: 内置超管(默认就叫localadmin)永远在列,local_only_accounts点名的账号也算;把它设成false就是彻底只认免登。 - 免登的身份映射只认
sub(accounts.hub_user_id),不按姓名或邮箱合并账号。只有口令那条路 允许按账号名认领一条同名本地账号——本人当场报了账号名、又过了 Hub 的口令校验;认领只补空的 主键,已经绑着别人主键就回account_identity_conflict,不建影子账号放人进来。 - 免登的落地地址(Hub 的
launch_url)填后端回调/api/v1/auth/sso/callback:票据只在 "浏览器 → 本系统 → Hub" 这一趟里出现,前端脚本、浏览历史与 Referer 都拿不到它。后端验完票 只 302 回/sso,地址上带的是一条 60 秒即失效、只能用一次、还绑着 HttpOnly Cookie 的短码。 要抄的完整地址在/org/hub-sync页与GET /api/v1/auth/hub/status的sso.callbackUrl。
联调与排障看 /org/hub-sync:两条密钥状态、门户落地地址、两条节奏、当前游标、最近一次同步
的四态与错误原文。落法、一次性短码、state 两层校验,以及与 unisoa 哪几处有意不同,
见 docs/统一身份登录.md。
部署
# 生产
cd backend # 先填 config.prod.toml:库账号、监听地址、落盘路径
chmod 600 config.prod.toml # 里面密钥一律留空,改用 PMS_* 环境变量注入
export PMS_ENV=prod
python3 run.py # 或用 gunicorn/uvicorn 多 worker 起
# 前端
cd frontend && npm run build # 产物在 dist/,同域反向代理到 /api
Nginx 关键两条:/api 反代到后端 8383;dist 静态资源交给前端路由做 try_files 回落 index.html。
生产同域部署时 CORS 可以留空。