docs: T+ 清单升至 v1.7 并清理过期版本文件
- 新增 docs/T+对接数据需求清单_v1.7_2026-10-20.xlsx（v1.6 可读性改造 的进一步结构重构：结论总览首屏、业务列前置、技术列后置分区） - 保留 v1.6 供对照；删除已被替代的 T+ 清单 2026-10-15/v1.4/v1.5、 待澄清问题清单 2026-10-15（两份）、待确认事项排序表 2026-10-16 （两份）与 2026-10-13 阶段报告（均有 10-19/10-20 后继文档） - 新增部署硬件需求（txt 源文与 docx 说明） Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
liuwenxinandClaude Code committed
1 parent
ebc9595de2
commit
94e2957359
12 files changed
+241
-154
No files matched your search
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
+241
@@ -0,0 +1,241 @@
|
|||||||
|
衍水集团营销人员工资管理系统
|
||||||
|
部署硬件需求说明
|
||||||
|
================================================================
|
||||||
|
版本：v1.0
|
||||||
|
日期：2026-10-21
|
||||||
|
适用：内部系统部署（数十人并发，无公网访问）
|
||||||
|
依据：仓库实际运行架构（docker/docker-compose.dev.yml、backend/pyproject.toml、
|
||||||
|
backend/app/core/db.py、docs/备份恢复手册.md、ai-aux/AI_CONTEXT.md）
|
||||||
|
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
一、结论摘要（先看这一节）
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
推荐配置：2 核 CPU / 8 GB 内存 / 100 GB SSD（Linux 单机）
|
||||||
|
最低配置：2 核 CPU / 4 GB 内存 / 100 GB SSD
|
||||||
|
演示配置：1 核 CPU / 2 GB 内存 / 40 GB SSD（仅限试用，不适合正式使用）
|
||||||
|
|
||||||
|
一句话：内部系统的瓶颈不在 CPU，而在「内存余量」和「磁盘容量」。
|
||||||
|
内存从 4 GB 升到 8 GB 的成本极低，却能一次性消除以后所有内存不足的排查；
|
||||||
|
磁盘不要按当前数据量买，要按「备份 + 恢复演练」的双倍空间买。
|
||||||
|
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
二、负载前提（为什么是这个配置）
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
以下事实全部来自本仓库，不是通用模板：
|
||||||
|
|
||||||
|
1) 内部系统、数十人并发
|
||||||
|
出处：ai-aux/AI_CONTEXT.md:101「并发极低（内部系统数十人）」
|
||||||
|
含义：CPU 核心数不是瓶颈，2 核足以支撑全部并发请求。
|
||||||
|
|
||||||
|
2) 全栈同步架构 + 单 worker，重活走线程池
|
||||||
|
出处：CLAUDE.md（分层约定）、backend/app/core/db.py:29
|
||||||
|
含义：一个请求占用一个线程；绩效批量核算、Excel 导出会短暂吃满一个核，
|
||||||
|
因此要留出至少 1 个空闲核给后端，避免请求排队。
|
||||||
|
|
||||||
|
3) MySQL 8.0 + Redis 7 双容器，Redis 开启 AOF
|
||||||
|
出处：docker/docker-compose.dev.yml:11、:44
|
||||||
|
含义：MySQL 是内存消耗大户（默认配置下性能很差，必须调参）；
|
||||||
|
Redis 只存验证码、Token 黑名单、登录失败计数，用量极小（<50 MB）。
|
||||||
|
|
||||||
|
4) 备份策略：每日全量 gz + binlog 增量，各自保留 30 天
|
||||||
|
出处：docs/备份恢复手册.md:11
|
||||||
|
含义：磁盘需按「业务数据 + 索引 + 30 天 binlog + 30 份全量备份」计算。
|
||||||
|
|
||||||
|
5) 恢复演练需恢复到独立临时库 payroll_drill_*
|
||||||
|
出处：docs/备份恢复手册.md:45
|
||||||
|
含义：演练瞬间需要约「2 倍数据库体积」的可用空间。
|
||||||
|
这是最容易被低估的一项，磁盘卡着下限买会在第一次演练时爆盘。
|
||||||
|
|
||||||
|
6) 报表导出用 openpyxl 全量载入内存
|
||||||
|
出处：backend/app/services/report_export.py:18
|
||||||
|
含义：导出大报表时后端进程内存峰值会翻倍，必须在内存预算里留余量。
|
||||||
|
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
三、正式生产推荐配置（内部系统，数十人）
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
项目 规格 说明
|
||||||
|
----------------------------------------------------------------
|
||||||
|
CPU 2 核（推荐 4 核） 2 核给容器与 MySQL，
|
||||||
|
1 核给 uvicorn（workers=2 上限），
|
||||||
|
1 核余量给系统与备份任务。
|
||||||
|
|
||||||
|
内存 8 GB（最低 4 GB） 8 GB 才有余量承受
|
||||||
|
「导出 + 核算 + 备份」同时发生。
|
||||||
|
|
||||||
|
磁盘 100 GB SSD（推荐 200 GB） 必须是 SSD。HDD 上 MySQL 的
|
||||||
|
ON UPDATE CURRENT_TIMESTAMP
|
||||||
|
高频写入会明显拖慢。
|
||||||
|
|
||||||
|
网络 内网千兆 无需公网 IP、域名、SSL 证书、CDN。
|
||||||
|
|
||||||
|
操作系统 Linux 推荐 Ubuntu 22.04 LTS / Rocky 9。
|
||||||
|
（Ubuntu 22.04 / Rocky 9） 备份、恢复、巡检脚本全部是 .sh
|
||||||
|
（scripts/ 目录），Linux 为原生路径。
|
||||||
|
若必须用 Windows Server，需 2022 +
|
||||||
|
WSL2 或 Git Bash 运行脚本。
|
||||||
|
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
四、内存分配明细（8 GB 的具体切法）
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
组件 建议占用 关键设置与说明
|
||||||
|
----------------------------------------------------------------
|
||||||
|
MySQL 8.0 3.5 GB innodb_buffer_pool_size = 2G
|
||||||
|
★ 默认仅 128 MB，不调会大量走磁盘，
|
||||||
|
MySQL 会成为整机最慢的一环。
|
||||||
|
|
||||||
|
后端 uvicorn 1.5 GB workers = 2
|
||||||
|
报表导出时单 worker 峰值可达 600 MB ~ 1 GB
|
||||||
|
（openpyxl 全量载入内存）。
|
||||||
|
|
||||||
|
Redis 7 256 MB maxmemory 256mb
|
||||||
|
实际用量 < 50 MB，设置上限只为兜底防失控。
|
||||||
|
|
||||||
|
Nginx + 系统 1 GB 静态资源（前端 dist）+ 反向代理 /api。
|
||||||
|
|
||||||
|
余量 1.75 GB mysqldump 备份进程、binlog 压缩、系统缓存。
|
||||||
|
|
||||||
|
----------------------------------------------------------------
|
||||||
|
4 GB 内存版（最低配置）的分配：
|
||||||
|
MySQL 1.5~2 GB（innodb_buffer_pool_size = 1G）
|
||||||
|
后端 0.8~1 GB
|
||||||
|
Redis 128 MB（maxmemory 128mb）
|
||||||
|
Docker + Nginx + 系统 0.6 GB
|
||||||
|
余量 ~0.6 GB
|
||||||
|
★ 这是「刚好够用」，一旦「导出报表」与「每日备份」撞在同一时刻，
|
||||||
|
OOM Killer 会优先杀 MySQL。这就是推荐 8 GB 的原因。
|
||||||
|
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
五、磁盘空间算式（100 GB 的来历）
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
项目 估算占用
|
||||||
|
----------------------------------------------------------------
|
||||||
|
业务数据（数十人，5 年） ≈ 1 GB
|
||||||
|
索引 + binlog 30 天（ROW 格式） ≈ 5 GB
|
||||||
|
全量备份 30 份（gz，约数据量 20%） ≈ 6 GB
|
||||||
|
恢复演练临时库（峰值 = 2 倍数据量） ≈ 2 GB
|
||||||
|
系统 + Docker 镜像 + 应用日志 ≈ 25 GB
|
||||||
|
----------------------------------------------------------------
|
||||||
|
合计 ≈ 39 GB
|
||||||
|
|
||||||
|
结论：100 GB 可支撑 2~3 年不需扩容。
|
||||||
|
按 docs/备份恢复手册.md:87 的 80% 磁盘水位告警，100 GB 有充足缓冲。
|
||||||
|
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
六、内部部署必须调整的四项（现有配置存在隐患）
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
1) 数据库端口必须收敛，不能监听所有网卡
|
||||||
|
现状：docker/docker-compose.dev.yml:27 为 "3306:3306"，
|
||||||
|
:48 为 "6379:6379"，等价于绑定 0.0.0.0。
|
||||||
|
风险：内网任何一台办公电脑都能直连 MySQL 试 root 密码。
|
||||||
|
改法（二选一）：
|
||||||
|
A. 只允许宿主机访问
|
||||||
|
ports:
|
||||||
|
- "127.0.0.1:3306:3306"
|
||||||
|
- "127.0.0.1:6379:6379"
|
||||||
|
B. 后端与数据库在同一 compose 网络内时，直接删掉这两行 ports，
|
||||||
|
容器之间通过服务名互访，宿主机只暴露 80/443。
|
||||||
|
|
||||||
|
2) 前端必须构建成静态文件 + Nginx 反向代理
|
||||||
|
禁止把 vite dev 服务器当正式环境用：
|
||||||
|
开发服务器会暴露全部源码，且不提供任何访问控制。
|
||||||
|
正式做法：pnpm build 产出 frontend/dist，由 Nginx 托管，
|
||||||
|
/api 反向代理到后端 8000 端口。
|
||||||
|
|
||||||
|
3) 备份必须异地留一份
|
||||||
|
内部系统最常见的「数据全丢」场景就是单机故障。
|
||||||
|
在 scripts/backup_full.sh 之后追加一步 rsync 到 NAS 或公司文件服务器。
|
||||||
|
|
||||||
|
4) 提前预留反向代理层
|
||||||
|
不接公网就不需要 WAF / CDN / SSL。
|
||||||
|
但如果公司后续有统一域名单点登录（SSO）规划，
|
||||||
|
Nginx 反代层要提前留好，避免到时大改架构。
|
||||||
|
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
七、三档速查表
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
场景 CPU 内存 磁盘 备注
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
试用 / 演示（< 5 人） 1 核 2 GB 40 GB SSD 仅跑小数据量；
|
||||||
|
导出大报表会 OOM
|
||||||
|
|
||||||
|
正式内部（数十人） 2 核 4 GB（建议 8 GB）100 GB SSD 推荐方案
|
||||||
|
【推荐】
|
||||||
|
|
||||||
|
内部 + 冗余 4 核 ×2 8 GB ×2 200 GB SSD ×2 含从库与监控；
|
||||||
|
（从库 + 监控） 工资系统若需
|
||||||
|
审计级可靠性
|
||||||
|
值得投入
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
八、可选加速项（非必须）
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
1) 图表库已本地化
|
||||||
|
ECharts 静态文件已放在 docs/design/echarts.min.js，
|
||||||
|
前端自托管即可，不依赖外网 CDN，符合「内网加载不可靠」的既定决策。
|
||||||
|
|
||||||
|
2) 日志盘分离
|
||||||
|
若开启审计日志长期留存，把 backend/logs/ 挂载到独立磁盘，
|
||||||
|
避免日志写满系统盘导致 MySQL 无法写入。
|
||||||
|
|
||||||
|
3) 备份异地化
|
||||||
|
本机备份 + 定时 rsync 到 NAS 或对象存储，构成「本地 + 异地」两份。
|
||||||
|
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
九、生产环境仍需完成的事项（本文件之外）
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
1) 生成 docker/docker-compose.prod.yml：
|
||||||
|
- 端口收敛到 127.0.0.1
|
||||||
|
- MySQL innodb_buffer_pool_size 等参数调优
|
||||||
|
- 容器 mem_limit / cpus 资源限制
|
||||||
|
- Nginx 反向代理静态前端 + /api
|
||||||
|
|
||||||
|
2) 后端启动参数由开发模式改为生产模式：
|
||||||
|
- 去掉 --reload（生产环境必须去掉）
|
||||||
|
- 设置 workers=2
|
||||||
|
|
||||||
|
3) backend/.env 中 APP_SECRET_KEY 必须换成强随机值，
|
||||||
|
MYSQL_PASSWORD / REDIS_PASSWORD 两处（docker/.env 与 backend/.env）保持一致。
|
||||||
|
|
||||||
|
4) 首次部署执行 alembic upgrade head，并创建管理员账号：
|
||||||
|
uv run python -m app.cli create-admin --username admin
|
||||||
|
|
||||||
|
5) 配置每日定时任务：全量备份 + 增量归档（见 docs/备份恢复手册.md）
|
||||||
|
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
十、附：数据来源索引
|
||||||
|
================================================================
|
||||||
|
|
||||||
|
ai-aux/AI_CONTEXT.md:101 并发规模判断（数十人）
|
||||||
|
docker/docker-compose.dev.yml:11 MySQL 8.0 容器
|
||||||
|
docker/docker-compose.dev.yml:27 MySQL 端口映射（需收敛）
|
||||||
|
docker/docker-compose.dev.yml:44 Redis 7 容器与 AOF
|
||||||
|
docker/docker-compose.dev.yml:48 Redis 端口映射（需收敛）
|
||||||
|
backend/app/core/db.py:29 同步引擎与连接池配置
|
||||||
|
backend/app/services/report_export.py:18 报表导出（内存峰值来源）
|
||||||
|
docs/备份恢复手册.md:11 备份策略
|
||||||
|
docs/备份恢复手册.md:45 恢复演练临时库
|
||||||
|
docs/备份恢复手册.md:87 磁盘水位 80% 告警阈值
|
||||||
|
scripts/ 备份 / 恢复 / 巡检脚本（.sh）
|
||||||
|
|
||||||
|
================================================================
|
||||||
|
（文件结束）
|
||||||
Binary file not shown.
@@ -1,154 +0,0 @@
|
|||||||
# 衍水集团营销人员工资管理系统项目阶段报告
|
|
||||||
|
|
||||||
- **报告日期**：2026-10-13
|
|
||||||
- **报告范围**：需求澄清、技术底座、系统管理、M1 参数体系、M2 当前进展与后续计划
|
|
||||||
- **项目分支**：`feat/base-business-data`
|
|
||||||
- **阶段结论**：项目已从“需求与底座建设”进入 **M2 基础数据管理开发期**；M1 已形成可验收闭环，M2 数据模型与迁移初稿已落地，但接口、页面与模块级测试尚未完成。
|
|
||||||
|
|
||||||
## 一、3P 阶段摘要
|
|
||||||
|
|
||||||
### Progress（进展）
|
|
||||||
|
|
||||||
已完成需求裁决、开发环境、数据库基础设计、登录鉴权、系统管理、前端框架与 M1 系统设置参数体系。M1 覆盖岗位角色、公式模板、16 项参数种子、时点化取值、版本留痕、参数预览与 Excel 导出；最近一次全量回归为后端 406 个用例与 28 项端到端检查通过。当前 M2 已完成人员、区域、计划、产品、客户、归属留痕六类表的模型与 V4 迁移初稿。
|
|
||||||
|
|
||||||
### Plans（计划）
|
|
||||||
|
|
||||||
短期优先完成 M2：在既有六表基础上补齐仓储、服务、接口、前端页面、审计与模块测试，并完成双轨迁移一致性验证。随后进入业务数据管理，为绩效核算提供业务单据与回款数据输入。报表与 T+ 同步继续后置，待业务数据模型稳定和 IT 字段映射确认后实施。
|
|
||||||
|
|
||||||
### Problems（问题）
|
|
||||||
|
|
||||||
当前无业务需求阻塞，但 M2 代码尚未提交，需防止结构设计与后续接口实现长期分叉。T+ 字段映射、幂等唯一键与失败重试策略仍待 IT 确认；经理个人户业绩进入 12.5%+5% 的衔接口径需在核算模块开工前确认。原需求文档存在已裁决作废条款，对外引用前需修订或明确以对照表 v2 为准。
|
|
||||||
|
|
||||||
## 二、阶段定位与完成度
|
|
||||||
|
|
||||||
| 维度 | 当前状态 | 说明 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| 项目阶段 | 开发期 | M1 已交付，M2 进行中 |
|
|
||||||
| 整体完成度 | 14% | 管理口径；M2 尚未达到可交付节点，仅按结构设计进展小幅上调 |
|
|
||||||
| 交付主线 | M2 基础数据管理 | 六表结构与 T+ 预留已形成初稿 |
|
|
||||||
| 质量状态 | M1 回归通过 | 后端 406 用例、e2e 登录 8 项 / 系统管理 13 项 / 参数 7 项通过 |
|
|
||||||
| 主要风险 | 外部对接与口径追溯 | T+ 映射未定；需规含作废条款 |
|
|
||||||
|
|
||||||
> 说明：整体完成度用于管理沟通，不等同于代码行占比。M2 仅完成数据结构层，接口、页面和模块级测试未完成，因此不能标记为模块交付。
|
|
||||||
|
|
||||||
## 三、已完成成果
|
|
||||||
|
|
||||||
### 1. 需求与执行口径
|
|
||||||
|
|
||||||
- 业务方已回执《问题与解决方案对照表_v2.xlsx》，28 项争议全部落定。
|
|
||||||
- 2026-10-12 后，需求以对照表 v2 与《2026.9.8修改方案.docx》的裁决口径为准。
|
|
||||||
- 关键口径已固化：回款天数自然日累计且发货日计第 1 天；毛利润率不含运费；业务员计提按 1～360 天线性递减、361 天及以上固定 4‰；企业户 3‰；信息员按销售额 1‰；参数按回款到账日时点取值。
|
|
||||||
- 支付环节的起付比例、支付权重、预付款、以物抵顶均按可配置参数预留。
|
|
||||||
|
|
||||||
### 2. 技术与运行底座
|
|
||||||
|
|
||||||
- 后端六层结构建立：`api → services → repositories → models`，`schemas` 承载请求响应，`core` 处理横切能力。
|
|
||||||
- 统一响应、全局异常、结构化日志、审计脱敏、配置安全校验已落地。
|
|
||||||
- 本地环境基于 Docker Compose 编排 MySQL 8.0 与 Redis 7，使用命名卷持久化、业务账号最小权限、utf8mb4 字符集。
|
|
||||||
- 迁移采用 Alembic 生成并导出 `db/migration/V{n}__*.sql` 的双轨方式，兼顾开发迭代与生产脚本留存。
|
|
||||||
|
|
||||||
### 3. 登录鉴权与系统管理
|
|
||||||
|
|
||||||
- 登录链路包含图形验证码、JWT、登录失败限流、Token 黑名单与登录日志。
|
|
||||||
- 系统管理包含用户、角色、操作日志与日志查询，前后端闭环。
|
|
||||||
- 审计机制记录成功与失败操作，敏感字段按键名结构化脱敏，日志列表与详情分段加载。
|
|
||||||
|
|
||||||
### 4. M1 系统设置与参数体系
|
|
||||||
|
|
||||||
- 建立岗位角色、参数定义、变更批次、参数值四表。
|
|
||||||
- 公式模板以代码内有限集合注册，参数按生效日期时点化存储，避免用当前值重算历史。
|
|
||||||
- 提供 16 个管理端点，支持参数分组、版本管理、批次撤回、两日期对比、计算预览与 xlsx 导出。
|
|
||||||
- 前端交付岗位角色配置页、计提参数配置页、Bento 仪表盘与统一视觉体系。
|
|
||||||
- Code review 发现的 15 项问题已全部修复，并完成回归。
|
|
||||||
|
|
||||||
## 四、当前进行中工作
|
|
||||||
|
|
||||||
当前分支 `feat/base-business-data` 正在推进 M2 基础数据管理。已形成的结构设计包括：
|
|
||||||
|
|
||||||
| 数据对象 | 设计要点 | 后续消费方 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `personnel` | 人员档案、岗位角色、直属经理、试用期、工资标准与状态 | 基础数据、业务归属、绩效核算 |
|
|
||||||
| `personnel_regions` | 人员负责的产品辐射区域，1:N 子表 | 基础数据维护 |
|
|
||||||
| `personnel_plans` | 市场拓展计划与指标说明，先做自由条目容器 | T+ 字段映射确认后细化 |
|
|
||||||
| `products` | 产品名称与规格唯一，类别锚定折算阈值参数 | 业务数据与绩效核算 |
|
|
||||||
| `customers` | 公司名称加负责人唯一，客户分类作为计提规则锚点 | 业务数据与绩效核算 |
|
|
||||||
| `ownership_change_logs` | 客户与业务归属变更留痕，append-only，不回溯历史 | 审计与核算追溯 |
|
|
||||||
|
|
||||||
设计上已为 T+ 同步预留 `source_no`、`t_plus_id`、`sync_batch_no`、`synced_at`。由于 IT 尚未确认字段映射与幂等键，这些列暂为可空并仅对 `source_no` 建普通索引，待键语义确定后再以小迁移升级唯一约束。
|
|
||||||
|
|
||||||
**当前边界**：以上属于模型、Alembic 迁移、生产 SQL 与开发初始化脚本层面的初稿；M2 的 CRUD API、服务事务、前端页面、权限审计和完整测试仍待实现。相关文件当前未提交，不能视为已交付功能。
|
|
||||||
|
|
||||||
## 五、下一步计划
|
|
||||||
|
|
||||||
| 优先级 | 工作项 | 验收标准 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| P0 | 完成 M2 六表接口与服务 | 列表、详情、创建、更新、停用 / 删除保护可用；事务与审计完整 |
|
|
||||||
| P0 | 完成 M2 前端页面 | 人员、产品、客户管理页面复用现有分页与确认交互，类型检查通过 |
|
|
||||||
| P0 | 补齐 M2 测试与迁移一致性检查 | 单元测试、集成测试、schema 同步测试通过 |
|
|
||||||
| P1 | 提交并评审 M2 | 提交信息符合规范，不直推共享主干 |
|
|
||||||
| P1 | 启动业务数据管理设计 | 明确业务、发货、回款、批次匹配与核销状态模型 |
|
|
||||||
| P1 | 确认核算前置口径 | 经理个人户业绩是否计入 12.5% 团队基数 |
|
|
||||||
| P2 | T+ 对接专项 | 字段映射、唯一键、去重、同步日志与失败重试策略由 IT 确认 |
|
|
||||||
|
|
||||||
## 六、风险与应对
|
|
||||||
|
|
||||||
| 风险 | 影响 | 当前应对 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| M2 结构初稿长期未提交 | 后续接口实现与表结构评审结论容易分叉 | 尽快完成最小可测闭环后提交，评审后再扩展 |
|
|
||||||
| T+ 字段映射未定 | 同步模块无法最终定幂等键与字段清洗规则 | 目标表预留同步字段；同步模块后置；不覆盖人工维护字段 |
|
|
||||||
| 需求文档存在作废条款 | 新成员或外部方按旧需规理解会产生口径冲突 | 以对照表 v2 与 9.8 修改方案为准；后续修订需规或加显著说明 |
|
|
||||||
| 经理个人户衔接口径待确认 | 影响绩效台账归属字段与经理绩效基数 | 在核算模块开工前作为必须裁决项跟踪 |
|
|
||||||
| 绩效金额精度风险 | 浮点误差会直接造成算错钱 | 金额使用 `Decimal`，比例斜率使用 `Fraction`；关键边界已有纯函数测试 |
|
|
||||||
|
|
||||||
## 七、技术选型理由
|
|
||||||
|
|
||||||
### 1. 后端：Python 3.12 + FastAPI
|
|
||||||
|
|
||||||
| 选型 | 理由 | 放弃的替代方案 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| Python 3.12 | `Decimal` 与 `Fraction` 能精确处理金额、千分比和 `4/360` 斜率；数据处理、Excel、后续 T+ 清洗生态成熟；版本锁定 3.12 避免新版本第三方轮子覆盖不稳 | Python 3.14：生态轮子覆盖尚不完备，兼容风险高 |
|
|
||||||
| FastAPI | 自动 OpenAPI、Pydantic 参数校验、依赖注入和统一异常模型适合内部管理系统；显式路由便于把算钱逻辑限定在 service 层 | Django：Admin 对 T+ 来源的数据 CRUD 复用价值有限，隐式 ORM 行为不利于工资核算追溯 |
|
|
||||||
| 同步 SQLAlchemy 2.0 | 项目并发压力低；绩效批量核算、Excel 导出和数据清洗是同步阻塞任务，同步路由由 FastAPI 放入线程池，避免阻塞事件循环 | 异步 SQLAlchemy：增加复杂度但没有对应吞吐收益 |
|
|
||||||
|
|
||||||
### 2. 数据与缓存：MySQL 8.0 + Redis 7
|
|
||||||
|
|
||||||
| 选型 | 理由 | 放弃的替代方案 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| MySQL 8.0 + InnoDB + utf8mb4 | 事务、外键、约束与审计留痕可靠；团队与运维熟悉度高；`DECIMAL` 支撑金额精度；utf8mb4 覆盖中文与特殊字符 | Excel / 文件库：无法承载并发、事务、权限与审计；NoSQL：缺少关系约束，不利薪酬追溯 |
|
|
||||||
| Alembic 双轨迁移 | 开发期可自动生成演进，生产保留按序 SQL 脚本，符合审计与发布要求 | 仅手写 SQL：模型与库结构易漂移；仅 Alembic：不满足生产脚本留存约定 |
|
|
||||||
| Redis 7 | 验证码、登录限流、Token 黑名单都需要带 TTL 的短生命周期状态；`GETDEL` 支撑验证码一次性消费 | 仅 MySQL：一次性状态表会增加清理与原子性复杂度 |
|
|
||||||
|
|
||||||
### 3. 前端：Vue 3 + TypeScript + Vite + Element Plus + Pinia
|
|
||||||
|
|
||||||
| 选型 | 理由 | 放弃的替代方案 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| Vue 3 + TypeScript | 组件生态成熟，类型约束能降低表单和接口字段错误；项目已沉淀路由、状态、分页与确认交互 | 新换框架：无业务收益，徒增迁移成本 |
|
|
||||||
| Vite | 启动与热更新快，开发体验好；生产构建链路简单 | Webpack：配置与维护成本更高 |
|
|
||||||
| Element Plus | 表格、表单、抽屉、分页、日期选择等管理端组件齐全，可快速交付后台页面 | 自研组件库：一期交付效率低 |
|
|
||||||
| Pinia | 轻量状态管理，适合登录态、用户信息与模块状态 | 大型全局状态方案：当前规模过度设计 |
|
|
||||||
|
|
||||||
### 4. 工程与质量：uv + pnpm + Docker Compose + pytest + Playwright
|
|
||||||
|
|
||||||
| 选型 | 理由 |
|
|
||||||
| --- | --- |
|
|
||||||
| uv | 锁定 Python 与依赖版本，安装速度快，避免“本机能跑、别处失败” |
|
|
||||||
| pnpm | 依赖硬链接节省空间，lockfile 保证前端可重复安装 |
|
|
||||||
| Docker Compose | 一条命令拉起 MySQL 与 Redis，版本固定、环境一致，不依赖开发者本机散装数据库 |
|
|
||||||
| pytest + fakeredis + Playwright | 单元、集成、端到端分层验证；fakeredis 让验证码和限流测试无需容器，浏览器测试覆盖真实登录与管理链路 |
|
|
||||||
|
|
||||||
### 5. 业务计算架构：公式模板 + 参数版本，而非规则引擎
|
|
||||||
|
|
||||||
一期公式骨架固定，变化的是比例、阈值、生效日期和岗位绑定，因此使用“代码内有限公式模板 + 参数时点化版本”足够，并且可测试、可审计、排错直观。引入规则引擎会增加公式调试、权限、留痕与回归成本，却不能消除业务口径澄清本身。若未来业务要求公式可由管理员自由编写，再评估规则引擎或表达式引擎，并保持计算入口兼容。
|
|
||||||
|
|
||||||
## 八、报告结论
|
|
||||||
|
|
||||||
项目基础能力和 M1 参数地基已经稳定，当前最短路径是完成 M2 基础数据管理的可测闭环，再进入业务数据管理。技术上应继续坚持“关系数据库约束 + 精确数值类型 + 时点化参数 + 审计留痕”的路线，不在 T+ 映射未定时提前锁死同步唯一键。管理上需重点跟踪 M2 提交、核算前口径确认和 T+ 对接三项。
|
|
||||||
|
|
||||||
## 附录：信息来源
|
|
||||||
|
|
||||||
- 项目入口与运行说明：[README.md](../README.md)
|
|
||||||
- 剩余开发路线：[2026-10-12-剩余开发计划.md](superpowers/plans/2026-10-12-剩余开发计划.md)
|
|
||||||
- 需求裁决：`docs/问题与解决方案对照表_v2.xlsx`
|
|
||||||
- 修改方案：`docs/2026.9.8修改方案.docx`
|
|
||||||
- 后端测试记录：[backend/tests/README.md](../backend/tests/README.md)
|
|
||||||
- 前端约定与测试：[frontend/README.md](../frontend/README.md)
|
|
||||||
Reference in new issue
Block a user