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
@@ -47,12 +47,25 @@ PRODUCT_CATEGORY_MUNICIPAL_WATER = "municipal_water"
|
||||
PRODUCT_CATEGORY_RAIL_TRANSIT = "rail_transit"
|
||||
PRODUCT_CATEGORIES = {PRODUCT_CATEGORY_MUNICIPAL_WATER, PRODUCT_CATEGORY_RAIL_TRANSIT}
|
||||
|
||||
# ===== 客户分类码（customers.customer_type，计提规则匹配锚点）=====
|
||||
CUSTOMER_TYPE_PERSONAL = "personal"
|
||||
CUSTOMER_TYPE_MANAGER_PERSONAL = "manager_personal"
|
||||
CUSTOMER_TYPE_ENTERPRISE = "enterprise"
|
||||
CUSTOMER_TYPES = {
|
||||
CUSTOMER_TYPE_PERSONAL,
|
||||
CUSTOMER_TYPE_MANAGER_PERSONAL,
|
||||
CUSTOMER_TYPE_ENTERPRISE,
|
||||
}
|
||||
|
||||
# ===== 操作日志词表（operation_logs 的 module / action 取值）=====
|
||||
# 集中定义避免各处硬编码导致日志值漂移；前端筛选下拉项与此保持一致
|
||||
MODULE_USER = "用户管理"
|
||||
MODULE_ROLE = "角色管理"
|
||||
MODULE_BUSINESS_ROLE = "岗位角色"
|
||||
MODULE_PARAM = "计提参数"
|
||||
MODULE_PERSONNEL = "人员管理"
|
||||
MODULE_PRODUCT = "产品管理"
|
||||
MODULE_CUSTOMER = "客户管理"
|
||||
|
||||
ACTION_CREATE = "新增"
|
||||
ACTION_UPDATE = "修改"
|
||||
|
||||
@@ -11,21 +11,30 @@
|
||||
|
||||
from app.models.base import Base, TimestampMixin
|
||||
from app.models.business_role import BusinessRole
|
||||
from app.models.customer import Customer, OwnershipChangeLog
|
||||
from app.models.login_log import LoginLog
|
||||
from app.models.operation_log import OperationLog
|
||||
from app.models.param import ParamChangeBatch, ParamDefinition, ParamValue
|
||||
from app.models.personnel import Personnel, PersonnelPlan, PersonnelRegion
|
||||
from app.models.product import Product
|
||||
from app.models.role import Permission, Role, RolePermission
|
||||
from app.models.user import User, UserRole
|
||||
|
||||
__all__ = [
|
||||
"Base",
|
||||
"BusinessRole",
|
||||
"Customer",
|
||||
"LoginLog",
|
||||
"OperationLog",
|
||||
"OwnershipChangeLog",
|
||||
"ParamChangeBatch",
|
||||
"ParamDefinition",
|
||||
"ParamValue",
|
||||
"Permission",
|
||||
"Personnel",
|
||||
"PersonnelPlan",
|
||||
"PersonnelRegion",
|
||||
"Product",
|
||||
"Role",
|
||||
"RolePermission",
|
||||
"TimestampMixin",
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
|
||||
from datetime import datetime
|
||||
|
||||
from sqlalchemy import DateTime, MetaData, text
|
||||
from sqlalchemy import DateTime, MetaData, String, text
|
||||
from sqlalchemy.dialects.mysql import BIGINT, TINYINT
|
||||
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
|
||||
|
||||
@@ -28,7 +28,14 @@ BIGINT_UNSIGNED = BIGINT(unsigned=True)
|
||||
# 状态类字段统一用 TINYINT（0/1 或少量枚举值）
|
||||
TINYINT_TYPE = TINYINT
|
||||
|
||||
__all__ = ["BIGINT_UNSIGNED", "TINYINT_TYPE", "Base", "TimestampMixin", "mysql_table_args"]
|
||||
__all__ = [
|
||||
"BIGINT_UNSIGNED",
|
||||
"TINYINT_TYPE",
|
||||
"Base",
|
||||
"TPlusSyncMixin",
|
||||
"TimestampMixin",
|
||||
"mysql_table_args",
|
||||
]
|
||||
|
||||
|
||||
class Base(DeclarativeBase):
|
||||
@@ -62,6 +69,30 @@ class TimestampMixin:
|
||||
)
|
||||
|
||||
|
||||
class TPlusSyncMixin:
|
||||
"""T+（用友）数据同步预留列，六张业务主表共用。
|
||||
|
||||
对照表 #26：T+ 对接的字段映射与幂等键语义未定（IT 牵头），故四列全部
|
||||
可空、不设唯一键 —— 键语义未定就锁死唯一约束，对接时大概率返工；
|
||||
source_no 先建普通索引承担查询与去重，IT 定键后以小迁移升级唯一约束。
|
||||
|
||||
同步守则（M4 同步模块必须遵守）：同步只写 T+ 侧字段与本组列，
|
||||
**不覆盖人工维护字段**（岗位/工资标准/归属/客户分类/业务状态等，
|
||||
各表注释已标注）。同步频率：一周一次定时 + 手动触发（对照表 #10）。
|
||||
"""
|
||||
|
||||
source_no: Mapped[str | None] = mapped_column(
|
||||
String(64),
|
||||
index=True,
|
||||
comment="T+ 原始单据号（同步幂等去重锚点；唯一键待 IT 定键后升级）",
|
||||
)
|
||||
t_plus_id: Mapped[str | None] = mapped_column(String(64), comment="T+ 系统内部标识")
|
||||
sync_batch_no: Mapped[str | None] = mapped_column(
|
||||
String(32), comment="同步批次号（同步模块写入）"
|
||||
)
|
||||
synced_at: Mapped[datetime | None] = mapped_column(DateTime, comment="最近同步时间")
|
||||
|
||||
|
||||
def mysql_table_args(comment: str, *extra: object) -> tuple[object, ...]:
|
||||
"""构造 MySQL 表的公共参数，返回可直接赋给 `__table_args__` 的元组。
|
||||
|
||||
|
||||
@@ -0,0 +1,121 @@
|
||||
"""客户模型：客户档案与归属变更留痕。
|
||||
|
||||
- 「公司名称 + 负责人」是业务唯一标识（需规 2.1.3）；负责人是客户公司的
|
||||
负责人**人名**（字符串），不是系统内的营销人员 —— 系统内归属另用
|
||||
owner_personnel_id 外键表达，两者语义不同
|
||||
- 归属变更只改主表当前值 + 插一条留痕，**不回溯历史**（对照表 #19）：
|
||||
历史核算结果在 M3 台账已固化，无需 effective_date 时点化设计
|
||||
- 留痕表（OwnershipChangeLog）对客户/业务/人员 ID 均为**无外键的冗余固化**：
|
||||
留痕是历史记录，被引用方被删除后记录仍须完整可读；RESTRICT 外键反而会
|
||||
把「删除客户」逼成 500。业务实体删除保护由服务层检查承担
|
||||
"""
|
||||
|
||||
from datetime import datetime
|
||||
|
||||
from sqlalchemy import DateTime, ForeignKey, Index, String, UniqueConstraint, text
|
||||
from sqlalchemy.orm import Mapped, mapped_column
|
||||
|
||||
from app.models.base import (
|
||||
BIGINT_UNSIGNED,
|
||||
TINYINT_TYPE,
|
||||
Base,
|
||||
TimestampMixin,
|
||||
TPlusSyncMixin,
|
||||
mysql_table_args,
|
||||
)
|
||||
|
||||
# 归属类型（ownership_change_logs.owner_type）
|
||||
OWNER_TYPE_CUSTOMER = 1
|
||||
OWNER_TYPE_BUSINESS = 2
|
||||
|
||||
|
||||
class Customer(Base, TimestampMixin, TPlusSyncMixin):
|
||||
"""客户表（需求 2.1.3）。customer_type 是计提规则匹配锚点（M3 消费）。"""
|
||||
|
||||
__tablename__ = "customers"
|
||||
__table_args__ = mysql_table_args(
|
||||
"客户表（公司名称+负责人为业务唯一标识；T+同步不覆盖客户分类）",
|
||||
UniqueConstraint("company_name", "owner_name", name="uk_customers_company_owner"),
|
||||
)
|
||||
|
||||
id: Mapped[int] = mapped_column(
|
||||
BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
|
||||
)
|
||||
company_name: Mapped[str] = mapped_column(String(128), nullable=False, comment="公司名称")
|
||||
owner_name: Mapped[str] = mapped_column(
|
||||
String(64), nullable=False, comment="客户负责人姓名（客户公司负责人的人名，非系统人员）"
|
||||
)
|
||||
contact_person: Mapped[str | None] = mapped_column(String(64), comment="联系人")
|
||||
contact_phone: Mapped[str | None] = mapped_column(String(20), comment="联系电话")
|
||||
address: Mapped[str | None] = mapped_column(String(255), comment="地址")
|
||||
industry: Mapped[str | None] = mapped_column(String(64), comment="所属行业（自由文本）")
|
||||
customer_type: Mapped[str] = mapped_column(
|
||||
String(32),
|
||||
nullable=False,
|
||||
server_default="personal",
|
||||
index=True,
|
||||
comment="客户分类：personal个人户 manager_personal经理个人户 enterprise企业户（计提规则匹配锚点；T+同步不覆盖）",
|
||||
)
|
||||
owner_personnel_id: Mapped[int | None] = mapped_column(
|
||||
BIGINT_UNSIGNED,
|
||||
ForeignKey("personnel.id", ondelete="RESTRICT"),
|
||||
index=True,
|
||||
comment="归属负责营销人员ID（手动修改不回溯历史，变更留痕见 ownership_change_logs）",
|
||||
)
|
||||
remark: Mapped[str | None] = mapped_column(String(255), comment="备注")
|
||||
|
||||
|
||||
class OwnershipChangeLog(Base):
|
||||
"""归属变更记录表（append-only，需求 2.1.3 + 对照表 #19）。
|
||||
|
||||
owner_type 区分客户归属/业务归属：1 → customer_id 非空，2 → business_id
|
||||
非空，由应用层校验（无外键，见模块 docstring 的固化论证）。
|
||||
前后值冗余固化（无外键）：人员被删除后留痕仍可读。
|
||||
"""
|
||||
|
||||
__tablename__ = "ownership_change_logs"
|
||||
__table_args__ = mysql_table_args(
|
||||
"归属变更记录表（append-only；客户/业务归属变更留痕，不回溯历史）",
|
||||
Index("idx_ownership_change_logs_customer_id", "customer_id"),
|
||||
Index("idx_ownership_change_logs_business_id", "business_id"),
|
||||
Index("idx_ownership_change_logs_create_time", "create_time"),
|
||||
)
|
||||
|
||||
id: Mapped[int] = mapped_column(
|
||||
BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
|
||||
)
|
||||
owner_type: Mapped[int] = mapped_column(
|
||||
TINYINT_TYPE, nullable=False, comment="归属类型：1客户归属 2业务归属"
|
||||
)
|
||||
customer_id: Mapped[int | None] = mapped_column(
|
||||
BIGINT_UNSIGNED,
|
||||
comment="客户ID（固化，owner_type=1 时非空）",
|
||||
)
|
||||
business_id: Mapped[int | None] = mapped_column(
|
||||
BIGINT_UNSIGNED,
|
||||
comment="业务ID（固化，owner_type=2 时非空）",
|
||||
)
|
||||
old_owner_personnel_id: Mapped[int | None] = mapped_column(
|
||||
BIGINT_UNSIGNED, comment="变更前负责营销人员ID（固化）"
|
||||
)
|
||||
new_owner_personnel_id: Mapped[int | None] = mapped_column(
|
||||
BIGINT_UNSIGNED, comment="变更后负责营销人员ID（固化）"
|
||||
)
|
||||
old_assistant_personnel_id: Mapped[int | None] = mapped_column(
|
||||
BIGINT_UNSIGNED, comment="变更前协助营销人员ID（固化，仅业务归属使用）"
|
||||
)
|
||||
new_assistant_personnel_id: Mapped[int | None] = mapped_column(
|
||||
BIGINT_UNSIGNED, comment="变更后协助营销人员ID（固化，仅业务归属使用）"
|
||||
)
|
||||
change_reason: Mapped[str | None] = mapped_column(String(255), comment="变更原因")
|
||||
operator_id: Mapped[int | None] = mapped_column(
|
||||
BIGINT_UNSIGNED,
|
||||
ForeignKey("users.id", ondelete="SET NULL"),
|
||||
comment="操作人ID（账号删除后置空）",
|
||||
)
|
||||
operator_name: Mapped[str] = mapped_column(
|
||||
String(64), nullable=False, comment="操作人用户名（冗余固化）"
|
||||
)
|
||||
create_time: Mapped[datetime] = mapped_column(
|
||||
DateTime, nullable=False, server_default=text("CURRENT_TIMESTAMP"), comment="创建时间"
|
||||
)
|
||||
@@ -0,0 +1,123 @@
|
||||
"""营销人员模型：人员档案、产品辐射区域与市场拓展计划。
|
||||
|
||||
- 岗位（business_role_id）决定计提公式模板，与工资标准同属「同步不覆盖」的
|
||||
人工维护字段（对照表 #26 落地口径，表注释标注供 M4 同步模块遵守）
|
||||
- manager_id 自引用表达「经理带团队」：NULL=经理本人或未分配；M3 经理
|
||||
12.5% 聚合、M4 部门汇总均按该关系展开，无需独立团队表
|
||||
- 一期营销人员不登录系统，不与 users 关联；若后续开放自助查工资再加列
|
||||
"""
|
||||
|
||||
from datetime import date
|
||||
from decimal import Decimal
|
||||
|
||||
from sqlalchemy import Date, ForeignKey, Numeric, String
|
||||
from sqlalchemy.orm import Mapped, mapped_column
|
||||
|
||||
from app.models.base import (
|
||||
BIGINT_UNSIGNED,
|
||||
TINYINT_TYPE,
|
||||
Base,
|
||||
TimestampMixin,
|
||||
TPlusSyncMixin,
|
||||
mysql_table_args,
|
||||
)
|
||||
|
||||
|
||||
class Personnel(Base, TimestampMixin, TPlusSyncMixin):
|
||||
"""营销人员表（需求 2.1.1）。
|
||||
|
||||
表名 personnel 为集合名词（单复数同形），本身即复数语义。
|
||||
试用期人员绩效照算不发放（对照表 #17），is_probation 供 M3 区分。
|
||||
"""
|
||||
|
||||
__tablename__ = "personnel"
|
||||
__table_args__ = mysql_table_args("营销人员表（T+同步不覆盖岗位与工资标准）")
|
||||
|
||||
id: Mapped[int] = mapped_column(
|
||||
BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
|
||||
)
|
||||
personnel_name: Mapped[str] = mapped_column(String(64), nullable=False, comment="姓名")
|
||||
business_role_id: Mapped[int] = mapped_column(
|
||||
BIGINT_UNSIGNED,
|
||||
ForeignKey("business_roles.id", ondelete="RESTRICT"),
|
||||
nullable=False,
|
||||
index=True,
|
||||
comment="岗位角色ID（决定计提公式模板；T+同步不覆盖）",
|
||||
)
|
||||
manager_id: Mapped[int | None] = mapped_column(
|
||||
BIGINT_UNSIGNED,
|
||||
ForeignKey("personnel.id", ondelete="RESTRICT"),
|
||||
index=True,
|
||||
comment="直属营销经理ID（NULL=经理本人或未分配；团队成员关系锚点）",
|
||||
)
|
||||
phone: Mapped[str | None] = mapped_column(String(20), comment="联系电话")
|
||||
hire_date: Mapped[date | None] = mapped_column(Date, comment="入职日期")
|
||||
is_probation: Mapped[int] = mapped_column(
|
||||
TINYINT_TYPE,
|
||||
nullable=False,
|
||||
server_default="0",
|
||||
comment="是否试用期：1是 0否（试用期绩效照算不发放）",
|
||||
)
|
||||
salary_standard: Mapped[Decimal | None] = mapped_column(
|
||||
Numeric(12, 2), comment="月工资标准（元；T+同步不覆盖）"
|
||||
)
|
||||
status: Mapped[int] = mapped_column(
|
||||
TINYINT_TYPE,
|
||||
nullable=False,
|
||||
server_default="1",
|
||||
comment="状态：1在职 0离职（离职人员不可再被业务/客户归属引用）",
|
||||
)
|
||||
remark: Mapped[str | None] = mapped_column(String(255), comment="备注")
|
||||
|
||||
|
||||
class PersonnelRegion(Base, TimestampMixin):
|
||||
"""产品辐射区域表（需求 2.1.1）：人员负责的产品辐射地理范围，1:N 子表。
|
||||
|
||||
随人员编辑整表替换维护，无独立管理诉求，故不加 T+ 预留列。
|
||||
"""
|
||||
|
||||
__tablename__ = "personnel_regions"
|
||||
__table_args__ = mysql_table_args("产品辐射区域表")
|
||||
|
||||
id: Mapped[int] = mapped_column(
|
||||
BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
|
||||
)
|
||||
personnel_id: Mapped[int] = mapped_column(
|
||||
BIGINT_UNSIGNED,
|
||||
ForeignKey("personnel.id", ondelete="RESTRICT"),
|
||||
nullable=False,
|
||||
index=True,
|
||||
comment="人员ID（personnel.id）",
|
||||
)
|
||||
region_name: Mapped[str] = mapped_column(
|
||||
String(128), nullable=False, comment="区域名称（产品辐射地理范围）"
|
||||
)
|
||||
remark: Mapped[str | None] = mapped_column(String(255), comment="备注")
|
||||
|
||||
|
||||
class PersonnelPlan(Base, TimestampMixin):
|
||||
"""市场拓展计划表（需求 2.1.1）：计划期间 + 计划内容 + 指标说明的自由条目。
|
||||
|
||||
结构化指标粒度待 T+ 字段映射确认，先以自由条目容器落地；条目最终由
|
||||
T+ 同步确定，故预留 source_no 单列（无索引：查询按 personnel_id 走）。
|
||||
"""
|
||||
|
||||
__tablename__ = "personnel_plans"
|
||||
__table_args__ = mysql_table_args("市场拓展计划表")
|
||||
|
||||
id: Mapped[int] = mapped_column(
|
||||
BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
|
||||
)
|
||||
personnel_id: Mapped[int] = mapped_column(
|
||||
BIGINT_UNSIGNED,
|
||||
ForeignKey("personnel.id", ondelete="RESTRICT"),
|
||||
nullable=False,
|
||||
index=True,
|
||||
comment="人员ID（personnel.id）",
|
||||
)
|
||||
plan_period: Mapped[str] = mapped_column(
|
||||
String(32), nullable=False, comment="计划期间（如 2026Q1、2026-05）"
|
||||
)
|
||||
plan_content: Mapped[str] = mapped_column(String(500), nullable=False, comment="计划内容")
|
||||
target_desc: Mapped[str | None] = mapped_column(String(255), comment="指标说明（文字描述）")
|
||||
source_no: Mapped[str | None] = mapped_column(String(64), comment="T+ 原始条目号（预留）")
|
||||
@@ -0,0 +1,58 @@
|
||||
"""产品模型：产品主数据。
|
||||
|
||||
产品类别（product_category）是**折算阈值的行级锚点**：混合业务按产品逐条
|
||||
计算（对照表 #14），阈值本身由 M1 参数 `product.threshold` 按 PRODUCT_CATEGORY
|
||||
维度承担（#28「全部阈值统一在系统设置维护」），本表不建阈值列 —— 两处维护
|
||||
必然漂移。类别值域与 M1 参数维度共用 PRODUCT_CATEGORIES 常量。
|
||||
"""
|
||||
|
||||
from decimal import Decimal
|
||||
|
||||
from sqlalchemy import Numeric, String, UniqueConstraint
|
||||
from sqlalchemy.orm import Mapped, mapped_column
|
||||
|
||||
from app.models.base import (
|
||||
BIGINT_UNSIGNED,
|
||||
TINYINT_TYPE,
|
||||
Base,
|
||||
TimestampMixin,
|
||||
TPlusSyncMixin,
|
||||
mysql_table_args,
|
||||
)
|
||||
|
||||
|
||||
class Product(Base, TimestampMixin, TPlusSyncMixin):
|
||||
"""产品表（需求 2.1.2）。停用（status=0）为主，不物理删除。"""
|
||||
|
||||
__tablename__ = "products"
|
||||
__table_args__ = mysql_table_args(
|
||||
"产品表（类别锚定折算阈值参数；T+同步不覆盖产品类别）",
|
||||
UniqueConstraint("product_name", "spec_model", name="uk_products_name_spec"),
|
||||
)
|
||||
|
||||
id: Mapped[int] = mapped_column(
|
||||
BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
|
||||
)
|
||||
product_name: Mapped[str] = mapped_column(String(128), nullable=False, comment="产品名称")
|
||||
spec_model: Mapped[str] = mapped_column(
|
||||
String(128),
|
||||
nullable=False,
|
||||
server_default="''",
|
||||
comment="规格型号（空串而非 NULL：参与组合唯一键，MySQL 组合索引对 NULL 不去重）",
|
||||
)
|
||||
unit: Mapped[str | None] = mapped_column(String(16), comment="计量单位")
|
||||
stock_quantity: Mapped[Decimal | None] = mapped_column(
|
||||
Numeric(14, 2), comment="数量（T+ 同步原样存储，语义待 IT 确认）"
|
||||
)
|
||||
sale_price: Mapped[Decimal | None] = mapped_column(
|
||||
Numeric(14, 4), comment="销售单价（元，T+ 同步）"
|
||||
)
|
||||
product_category: Mapped[str] = mapped_column(
|
||||
String(32),
|
||||
nullable=False,
|
||||
comment="产品类别：municipal_water市政水利 rail_transit轨道交通（决定折算阈值 30%/20%；T+同步不覆盖）",
|
||||
)
|
||||
status: Mapped[int] = mapped_column(
|
||||
TINYINT_TYPE, nullable=False, server_default="1", comment="状态：1启用 0停用"
|
||||
)
|
||||
remark: Mapped[str | None] = mapped_column(String(255), comment="备注")
|
||||
Reference in new issue
Block a user