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:
liuwenxin
parent
ebc9595de2
commit
94e2957359
Binary file not shown.
Binary file not shown.
Binary file not shown.
BIN
docs/T+对接数据需求清单_v1.6_2026-10-20.xlsx
Normal file
BIN
docs/T+对接数据需求清单_v1.6_2026-10-20.xlsx
Normal file
Binary file not shown.
BIN
docs/T+对接数据需求清单_v1.7_2026-10-20.xlsx
Normal file
BIN
docs/T+对接数据需求清单_v1.7_2026-10-20.xlsx
Normal file
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
241
docs/部署硬件需求.txt
Normal file
241
docs/部署硬件需求.txt
Normal file
@ -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）
|
||||
|
||||
================================================================
|
||||
（文件结束）
|
||||
BIN
docs/部署硬件需求说明.docx
Normal file
BIN
docs/部署硬件需求说明.docx
Normal file
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)
|
||||
Loading…
Reference in New Issue
Block a user