fourcal-pms/README.md

19 KiB
Raw Permalink Blame History

四算项目管理系统(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 主表。

设计上的几个决定

  1. biz_revision 取代老系统的 _temp 影子表。 概算/预算的每一版都是一行 biz_revision, 所有明细行带 revision_id。送审冻结的是版本号,不是复制一份表。
  2. 计算快照是唯一事实。 calc_snapshot.payload_json 存完整结果, project 表上的利润列只是投影,由 biz.apply_projection 写入。对账看快照,不看主表。
  3. 审批去 Activiti。 流程定义/节点/实例/待办/流水五张表,与业务同库同事务。 "这单现在谁在审"变成一次查询。
  4. 数据权限是策略表,不是角色上的一个字段。 5 种主体 × 10 种范围 × allow/deny × 可嵌套 条件树,能表达"同一个人不同列表不同范围"。详见《数据权限设计》。
  5. 口径可配置并带版本号。 老系统写死的 2.8% 管理费率、10% 差旅限额、价内税公式、 零分母行为都是 system_config 里 calc. 开头的业务参数,在「系统 → 计算口径」页面上改、 保存即生效,双跑对账时切回老口径复现,version 随快照留痕。配置文件里一条计算规则都不留。
  6. 下拉框取值统一进数据字典。 以前一份枚举写三处:model 的 LABELS、接口里现拼 的 [{value,label}]、前端视图里的常量数组——项目类型就因此对不上(接口叫"工程集成类", 列表页写"系统集成"),采购明细的产品归属还给过内核根本不认的编码,选了不报错、钱也不投影。 现在 dict_type / dict_item 是运行期唯一来源:随 /bootstrap 下发,页面用 DictSelect 按编码取值;「系统 → 数据字典」能改名、排序、停用、加自定义字典,保存即生效。 代码那份 LABELS 退成兜底与护栏——内置取值不许改也不许删(业务代码按它判分支), 只在界面上提供"恢复默认"。字典管候选项和展示名,不管校验:能不能送审、走哪条分支 仍然看代码常量,否则改个名字就能把状态机改出洞。
  7. 前端砍掉了双层页签。 明细表从"页签"降级成"目录",计算结果常驻右手边。 详见《前端布局方案》。

数据迁移

老四算(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 可以留空。