feat(base): 新增基础数据六表及 V4 迁移（人员/辐射区域/拓展计划/产品/客户/归属留痕）
- TPlusSyncMixin 统一 T+ 同步预留四列（可空+普通索引，唯一键待 IT 定键后升级） - 留痕表实体 ID 无外键冗余固化，删除保护由服务层承担 - init-dev.sql 同步六表 DDL，alembic_version 标记更新 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
liuwenxinandClaude Code committed
1 parent
4552f2e703
commit
f22d14e439
12 files changed
+1083
-4
No files matched your search
@@ -0,0 +1,154 @@
|
||||
# 衍水集团营销人员工资管理系统项目阶段报告
|
||||
|
||||
- **报告日期**：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