diff --git a/backend/alembic/versions/e1133a7c670a_add_base_data_tables.py b/backend/alembic/versions/e1133a7c670a_add_base_data_tables.py new file mode 100644 index 0000000..2f4c3bf --- /dev/null +++ b/backend/alembic/versions/e1133a7c670a_add_base_data_tables.py @@ -0,0 +1,181 @@ +"""基础数据管理六表：人员/辐射区域/拓展计划/产品/客户/归属变更留痕（M2） + +- personnel / personnel_regions / personnel_plans：人员档案及其 1:N 子表 +- products：产品主数据（类别锚定折算阈值参数） +- customers：客户档案（公司名称+负责人为业务唯一标识） +- ownership_change_logs：归属变更留痕（append-only，不回溯历史） +- 六张表的 T+ 同步预留列（source_no 等）全部可空、不设唯一键（对照表 #26） + +Revision ID: e1133a7c670a +Revises: bfbda9c3191d +Create Date: 2026-10-13 09:36:02.219248 + +""" +from collections.abc import Sequence + +from alembic import op +import sqlalchemy as sa +from sqlalchemy.dialects import mysql + +# revision identifiers, used by Alembic. +revision: str = 'e1133a7c670a' +down_revision: str | Sequence[str] | None = 'bfbda9c3191d' +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + """应用迁移。""" + # ### commands auto generated by Alembic - please adjust! ### + op.create_table('products', + sa.Column('id', mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment='主键ID'), + sa.Column('product_name', sa.String(length=128), nullable=False, comment='产品名称'), + sa.Column('spec_model', sa.String(length=128), server_default='', nullable=False, comment='规格型号（空串而非 NULL：参与组合唯一键，MySQL 组合索引对 NULL 不去重）'), + sa.Column('unit', sa.String(length=16), nullable=True, comment='计量单位'), + sa.Column('stock_quantity', sa.Numeric(precision=14, scale=2), nullable=True, comment='数量（T+ 同步原样存储，语义待 IT 确认）'), + sa.Column('sale_price', sa.Numeric(precision=14, scale=4), nullable=True, comment='销售单价（元，T+ 同步）'), + sa.Column('product_category', sa.String(length=32), nullable=False, comment='产品类别：municipal_water市政水利 rail_transit轨道交通（决定折算阈值 30%/20%；T+同步不覆盖）'), + sa.Column('status', mysql.TINYINT(), server_default='1', nullable=False, comment='状态：1启用 0停用'), + sa.Column('remark', sa.String(length=255), nullable=True, comment='备注'), + sa.Column('create_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False, comment='创建时间'), + sa.Column('update_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), nullable=False, comment='更新时间'), + sa.Column('source_no', sa.String(length=64), nullable=True, comment='T+ 原始单据号（同步幂等去重锚点；唯一键待 IT 定键后升级）'), + sa.Column('t_plus_id', sa.String(length=64), nullable=True, comment='T+ 系统内部标识'), + sa.Column('sync_batch_no', sa.String(length=32), nullable=True, comment='同步批次号（同步模块写入）'), + sa.Column('synced_at', sa.DateTime(), nullable=True, comment='最近同步时间'), + sa.PrimaryKeyConstraint('id', name=op.f('pk_products')), + sa.UniqueConstraint('product_name', 'spec_model', name='uk_products_name_spec'), + comment='产品表（类别锚定折算阈值参数；T+同步不覆盖产品类别）', + mysql_charset='utf8mb4', + mysql_collate='utf8mb4_general_ci', + mysql_engine='InnoDB' + ) + op.create_index(op.f('idx_products_source_no'), 'products', ['source_no'], unique=False) + op.create_table('ownership_change_logs', + sa.Column('id', mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment='主键ID'), + sa.Column('owner_type', mysql.TINYINT(), nullable=False, comment='归属类型：1客户归属 2业务归属'), + sa.Column('customer_id', mysql.BIGINT(unsigned=True), nullable=True, comment='客户ID（固化，owner_type=1 时非空）'), + sa.Column('business_id', mysql.BIGINT(unsigned=True), nullable=True, comment='业务ID（固化，owner_type=2 时非空）'), + sa.Column('old_owner_personnel_id', mysql.BIGINT(unsigned=True), nullable=True, comment='变更前负责营销人员ID（固化）'), + sa.Column('new_owner_personnel_id', mysql.BIGINT(unsigned=True), nullable=True, comment='变更后负责营销人员ID（固化）'), + sa.Column('old_assistant_personnel_id', mysql.BIGINT(unsigned=True), nullable=True, comment='变更前协助营销人员ID（固化，仅业务归属使用）'), + sa.Column('new_assistant_personnel_id', mysql.BIGINT(unsigned=True), nullable=True, comment='变更后协助营销人员ID（固化，仅业务归属使用）'), + sa.Column('change_reason', sa.String(length=255), nullable=True, comment='变更原因'), + sa.Column('operator_id', mysql.BIGINT(unsigned=True), nullable=True, comment='操作人ID（账号删除后置空）'), + sa.Column('operator_name', sa.String(length=64), nullable=False, comment='操作人用户名（冗余固化）'), + sa.Column('create_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False, comment='创建时间'), + sa.ForeignKeyConstraint(['operator_id'], ['users.id'], name=op.f('fk_ownership_change_logs_operator_id'), ondelete='SET NULL'), + sa.PrimaryKeyConstraint('id', name=op.f('pk_ownership_change_logs')), + comment='归属变更记录表（append-only；客户/业务归属变更留痕，不回溯历史）', + mysql_charset='utf8mb4', + mysql_collate='utf8mb4_general_ci', + mysql_engine='InnoDB' + ) + op.create_index(op.f('idx_ownership_change_logs_customer_id'), 'ownership_change_logs', ['customer_id'], unique=False) + op.create_index(op.f('idx_ownership_change_logs_business_id'), 'ownership_change_logs', ['business_id'], unique=False) + op.create_index(op.f('idx_ownership_change_logs_create_time'), 'ownership_change_logs', ['create_time'], unique=False) + op.create_table('personnel', + sa.Column('id', mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment='主键ID'), + sa.Column('personnel_name', sa.String(length=64), nullable=False, comment='姓名'), + sa.Column('business_role_id', mysql.BIGINT(unsigned=True), nullable=False, comment='岗位角色ID（决定计提公式模板；T+同步不覆盖）'), + sa.Column('manager_id', mysql.BIGINT(unsigned=True), nullable=True, comment='直属营销经理ID（NULL=经理本人或未分配；团队成员关系锚点）'), + sa.Column('phone', sa.String(length=20), nullable=True, comment='联系电话'), + sa.Column('hire_date', sa.Date(), nullable=True, comment='入职日期'), + sa.Column('is_probation', mysql.TINYINT(), server_default='0', nullable=False, comment='是否试用期：1是 0否（试用期绩效照算不发放）'), + sa.Column('salary_standard', sa.Numeric(precision=12, scale=2), nullable=True, comment='月工资标准（元；T+同步不覆盖）'), + sa.Column('status', mysql.TINYINT(), server_default='1', nullable=False, comment='状态：1在职 0离职（离职人员不可再被业务/客户归属引用）'), + sa.Column('remark', sa.String(length=255), nullable=True, comment='备注'), + sa.Column('create_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False, comment='创建时间'), + sa.Column('update_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), nullable=False, comment='更新时间'), + sa.Column('source_no', sa.String(length=64), nullable=True, comment='T+ 原始单据号（同步幂等去重锚点；唯一键待 IT 定键后升级）'), + sa.Column('t_plus_id', sa.String(length=64), nullable=True, comment='T+ 系统内部标识'), + sa.Column('sync_batch_no', sa.String(length=32), nullable=True, comment='同步批次号（同步模块写入）'), + sa.Column('synced_at', sa.DateTime(), nullable=True, comment='最近同步时间'), + sa.ForeignKeyConstraint(['business_role_id'], ['business_roles.id'], name=op.f('fk_personnel_business_role_id'), ondelete='RESTRICT'), + sa.ForeignKeyConstraint(['manager_id'], ['personnel.id'], name=op.f('fk_personnel_manager_id'), ondelete='RESTRICT'), + sa.PrimaryKeyConstraint('id', name=op.f('pk_personnel')), + comment='营销人员表（T+同步不覆盖岗位与工资标准）', + mysql_charset='utf8mb4', + mysql_collate='utf8mb4_general_ci', + mysql_engine='InnoDB' + ) + op.create_index(op.f('idx_personnel_business_role_id'), 'personnel', ['business_role_id'], unique=False) + op.create_index(op.f('idx_personnel_manager_id'), 'personnel', ['manager_id'], unique=False) + op.create_index(op.f('idx_personnel_source_no'), 'personnel', ['source_no'], unique=False) + op.create_table('customers', + sa.Column('id', mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment='主键ID'), + sa.Column('company_name', sa.String(length=128), nullable=False, comment='公司名称'), + sa.Column('owner_name', sa.String(length=64), nullable=False, comment='客户负责人姓名（客户公司负责人的人名，非系统人员）'), + sa.Column('contact_person', sa.String(length=64), nullable=True, comment='联系人'), + sa.Column('contact_phone', sa.String(length=20), nullable=True, comment='联系电话'), + sa.Column('address', sa.String(length=255), nullable=True, comment='地址'), + sa.Column('industry', sa.String(length=64), nullable=True, comment='所属行业（自由文本）'), + sa.Column('customer_type', sa.String(length=32), server_default='personal', nullable=False, comment='客户分类：personal个人户 manager_personal经理个人户 enterprise企业户（计提规则匹配锚点；T+同步不覆盖）'), + sa.Column('owner_personnel_id', mysql.BIGINT(unsigned=True), nullable=True, comment='归属负责营销人员ID（手动修改不回溯历史，变更留痕见 ownership_change_logs）'), + sa.Column('remark', sa.String(length=255), nullable=True, comment='备注'), + sa.Column('create_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False, comment='创建时间'), + sa.Column('update_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), nullable=False, comment='更新时间'), + sa.Column('source_no', sa.String(length=64), nullable=True, comment='T+ 原始单据号（同步幂等去重锚点；唯一键待 IT 定键后升级）'), + sa.Column('t_plus_id', sa.String(length=64), nullable=True, comment='T+ 系统内部标识'), + sa.Column('sync_batch_no', sa.String(length=32), nullable=True, comment='同步批次号（同步模块写入）'), + sa.Column('synced_at', sa.DateTime(), nullable=True, comment='最近同步时间'), + sa.ForeignKeyConstraint(['owner_personnel_id'], ['personnel.id'], name=op.f('fk_customers_owner_personnel_id'), ondelete='RESTRICT'), + sa.PrimaryKeyConstraint('id', name=op.f('pk_customers')), + sa.UniqueConstraint('company_name', 'owner_name', name='uk_customers_company_owner'), + comment='客户表（公司名称+负责人为业务唯一标识；T+同步不覆盖客户分类）', + mysql_charset='utf8mb4', + mysql_collate='utf8mb4_general_ci', + mysql_engine='InnoDB' + ) + op.create_index(op.f('idx_customers_customer_type'), 'customers', ['customer_type'], unique=False) + op.create_index(op.f('idx_customers_owner_personnel_id'), 'customers', ['owner_personnel_id'], unique=False) + op.create_index(op.f('idx_customers_source_no'), 'customers', ['source_no'], unique=False) + op.create_table('personnel_plans', + sa.Column('id', mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment='主键ID'), + sa.Column('personnel_id', mysql.BIGINT(unsigned=True), nullable=False, comment='人员ID（personnel.id）'), + sa.Column('plan_period', sa.String(length=32), nullable=False, comment='计划期间（如 2026Q1、2026-05）'), + sa.Column('plan_content', sa.String(length=500), nullable=False, comment='计划内容'), + sa.Column('target_desc', sa.String(length=255), nullable=True, comment='指标说明（文字描述）'), + sa.Column('source_no', sa.String(length=64), nullable=True, comment='T+ 原始条目号（预留）'), + sa.Column('create_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False, comment='创建时间'), + sa.Column('update_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), nullable=False, comment='更新时间'), + sa.ForeignKeyConstraint(['personnel_id'], ['personnel.id'], name=op.f('fk_personnel_plans_personnel_id'), ondelete='RESTRICT'), + sa.PrimaryKeyConstraint('id', name=op.f('pk_personnel_plans')), + comment='市场拓展计划表', + mysql_charset='utf8mb4', + mysql_collate='utf8mb4_general_ci', + mysql_engine='InnoDB' + ) + op.create_index(op.f('idx_personnel_plans_personnel_id'), 'personnel_plans', ['personnel_id'], unique=False) + op.create_table('personnel_regions', + sa.Column('id', mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment='主键ID'), + sa.Column('personnel_id', mysql.BIGINT(unsigned=True), nullable=False, comment='人员ID（personnel.id）'), + sa.Column('region_name', sa.String(length=128), nullable=False, comment='区域名称（产品辐射地理范围）'), + sa.Column('remark', sa.String(length=255), nullable=True, comment='备注'), + sa.Column('create_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False, comment='创建时间'), + sa.Column('update_time', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), nullable=False, comment='更新时间'), + sa.ForeignKeyConstraint(['personnel_id'], ['personnel.id'], name=op.f('fk_personnel_regions_personnel_id'), ondelete='RESTRICT'), + sa.PrimaryKeyConstraint('id', name=op.f('pk_personnel_regions')), + comment='产品辐射区域表', + mysql_charset='utf8mb4', + mysql_collate='utf8mb4_general_ci', + mysql_engine='InnoDB' + ) + op.create_index(op.f('idx_personnel_regions_personnel_id'), 'personnel_regions', ['personnel_id'], unique=False) + # ### end Alembic commands ### + + +def downgrade() -> None: + """回滚迁移。 + + **注意（autogenerate 不会替你处理）**：生成的 `op.drop_index` 与 + `op.drop_table` 顺序需人工检查 —— 若某索引是外键的唯一支撑索引， + 单独 drop_index 会报 MySQL 1553（needed in a foreign key constraint）。 + **整表回滚应只保留 `op.drop_table`**，DROP TABLE 会连带删除索引与外键。 + """ + op.drop_table('personnel_regions') + op.drop_table('personnel_plans') + op.drop_table('customers') + op.drop_table('personnel') + op.drop_table('ownership_change_logs') + op.drop_table('products') diff --git a/backend/app/core/constants.py b/backend/app/core/constants.py index 19d225a..a8c33f3 100644 --- a/backend/app/core/constants.py +++ b/backend/app/core/constants.py @@ -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 = "修改" diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py index 826689d..be20a84 100644 --- a/backend/app/models/__init__.py +++ b/backend/app/models/__init__.py @@ -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", diff --git a/backend/app/models/base.py b/backend/app/models/base.py index 59f932e..0ee13ad 100644 --- a/backend/app/models/base.py +++ b/backend/app/models/base.py @@ -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__` 的元组。 diff --git a/backend/app/models/customer.py b/backend/app/models/customer.py new file mode 100644 index 0000000..693cb7b --- /dev/null +++ b/backend/app/models/customer.py @@ -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="创建时间" + ) diff --git a/backend/app/models/personnel.py b/backend/app/models/personnel.py new file mode 100644 index 0000000..f9256a7 --- /dev/null +++ b/backend/app/models/personnel.py @@ -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+ 原始条目号（预留）") diff --git a/backend/app/models/product.py b/backend/app/models/product.py new file mode 100644 index 0000000..31f7aba --- /dev/null +++ b/backend/app/models/product.py @@ -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="备注") diff --git a/backend/tests/unit/test_models.py b/backend/tests/unit/test_models.py index d3b8069..ec0227b 100644 --- a/backend/tests/unit/test_models.py +++ b/backend/tests/unit/test_models.py @@ -23,8 +23,17 @@ EXPECTED_TABLES = { "param_definitions", "param_change_batches", "param_values", + "personnel", + "personnel_regions", + "personnel_plans", + "products", + "customers", + "ownership_change_logs", } +# 单复数同形的集合名词：本身即复数语义，不受「以 s 结尾」检查约束 +PLURAL_EXCEPTIONS = {"personnel"} + def _ddl(table_name: str) -> str: """返回某张表的建表 DDL 文本。""" @@ -43,7 +52,9 @@ class TestTableSet: def test_所有表名均为小写蛇形复数(self) -> None: for name in Base.metadata.tables: assert re.fullmatch(r"[a-z][a-z0-9_]*", name), f"表名 {name} 不符合小写蛇形" - assert name.endswith("s"), f"表名 {name} 应为复数" + # personnel 等集合名词单复数同形，本身即复数语义 + if name not in PLURAL_EXCEPTIONS: + assert name.endswith("s"), f"表名 {name} 应为复数" class TestNamingConvention: diff --git a/db/init/init-dev.sql b/db/init/init-dev.sql index b713020..468e351 100644 --- a/db/init/init-dev.sql +++ b/db/init/init-dev.sql @@ -254,6 +254,153 @@ CREATE INDEX idx_param_values_effective_date ON param_values (effective_date); CREATE INDEX idx_param_values_param_id_dimension_value_effective_date ON param_values (param_id, dimension_value, effective_date); +-- --------------------------------------------------------------------------- +-- 营销人员表（V4 迁移；T+ 同步不覆盖岗位与工资标准） +-- --------------------------------------------------------------------------- +CREATE TABLE personnel ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + personnel_name VARCHAR(64) NOT NULL COMMENT '姓名', + business_role_id BIGINT UNSIGNED NOT NULL COMMENT '岗位角色ID（决定计提公式模板；T+同步不覆盖）', + manager_id BIGINT UNSIGNED COMMENT '直属营销经理ID（NULL=经理本人或未分配；团队成员关系锚点）', + phone VARCHAR(20) COMMENT '联系电话', + hire_date DATE COMMENT '入职日期', + is_probation TINYINT NOT NULL COMMENT '是否试用期：1是 0否（试用期绩效照算不发放）' DEFAULT '0', + salary_standard DECIMAL(12, 2) COMMENT '月工资标准（元；T+同步不覆盖）', + status TINYINT NOT NULL COMMENT '状态：1在职 0离职（离职人员不可再被业务/客户归属引用）' DEFAULT '1', + remark VARCHAR(255) COMMENT '备注', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + source_no VARCHAR(64) COMMENT 'T+ 原始单据号（同步幂等去重锚点；唯一键待 IT 定键后升级）', + t_plus_id VARCHAR(64) COMMENT 'T+ 系统内部标识', + sync_batch_no VARCHAR(32) COMMENT '同步批次号（同步模块写入）', + synced_at DATETIME COMMENT '最近同步时间', + CONSTRAINT pk_personnel PRIMARY KEY (id), + CONSTRAINT fk_personnel_business_role_id FOREIGN KEY(business_role_id) REFERENCES business_roles (id) ON DELETE RESTRICT, + CONSTRAINT fk_personnel_manager_id FOREIGN KEY(manager_id) REFERENCES personnel (id) ON DELETE RESTRICT +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='营销人员表（T+同步不覆盖岗位与工资标准）' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_personnel_business_role_id ON personnel (business_role_id); + +CREATE INDEX idx_personnel_manager_id ON personnel (manager_id); + +CREATE INDEX idx_personnel_source_no ON personnel (source_no); + +-- --------------------------------------------------------------------------- +-- 产品辐射区域表（V4 迁移） +-- --------------------------------------------------------------------------- +CREATE TABLE personnel_regions ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + personnel_id BIGINT UNSIGNED NOT NULL COMMENT '人员ID（personnel.id）', + region_name VARCHAR(128) NOT NULL COMMENT '区域名称（产品辐射地理范围）', + remark VARCHAR(255) COMMENT '备注', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + CONSTRAINT pk_personnel_regions PRIMARY KEY (id), + CONSTRAINT fk_personnel_regions_personnel_id FOREIGN KEY(personnel_id) REFERENCES personnel (id) ON DELETE RESTRICT +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='产品辐射区域表' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_personnel_regions_personnel_id ON personnel_regions (personnel_id); + +-- --------------------------------------------------------------------------- +-- 市场拓展计划表（V4 迁移） +-- --------------------------------------------------------------------------- +CREATE TABLE personnel_plans ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + personnel_id BIGINT UNSIGNED NOT NULL COMMENT '人员ID（personnel.id）', + plan_period VARCHAR(32) NOT NULL COMMENT '计划期间（如 2026Q1、2026-05）', + plan_content VARCHAR(500) NOT NULL COMMENT '计划内容', + target_desc VARCHAR(255) COMMENT '指标说明（文字描述）', + source_no VARCHAR(64) COMMENT 'T+ 原始条目号（预留）', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + CONSTRAINT pk_personnel_plans PRIMARY KEY (id), + CONSTRAINT fk_personnel_plans_personnel_id FOREIGN KEY(personnel_id) REFERENCES personnel (id) ON DELETE RESTRICT +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='市场拓展计划表' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_personnel_plans_personnel_id ON personnel_plans (personnel_id); + +-- --------------------------------------------------------------------------- +-- 产品表（V4 迁移；类别锚定折算阈值参数，T+ 同步不覆盖产品类别） +-- --------------------------------------------------------------------------- +CREATE TABLE products ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + product_name VARCHAR(128) NOT NULL COMMENT '产品名称', + spec_model VARCHAR(128) NOT NULL COMMENT '规格型号（空串而非 NULL：参与组合唯一键，MySQL 组合索引对 NULL 不去重）' DEFAULT '', + unit VARCHAR(16) COMMENT '计量单位', + stock_quantity DECIMAL(14, 2) COMMENT '数量（T+ 同步原样存储，语义待 IT 确认）', + sale_price DECIMAL(14, 4) COMMENT '销售单价（元，T+ 同步）', + product_category VARCHAR(32) NOT NULL COMMENT '产品类别：municipal_water市政水利 rail_transit轨道交通（决定折算阈值 30%/20%；T+同步不覆盖）', + status TINYINT NOT NULL COMMENT '状态：1启用 0停用' DEFAULT '1', + remark VARCHAR(255) COMMENT '备注', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + source_no VARCHAR(64) COMMENT 'T+ 原始单据号（同步幂等去重锚点；唯一键待 IT 定键后升级）', + t_plus_id VARCHAR(64) COMMENT 'T+ 系统内部标识', + sync_batch_no VARCHAR(32) COMMENT '同步批次号（同步模块写入）', + synced_at DATETIME COMMENT '最近同步时间', + CONSTRAINT pk_products PRIMARY KEY (id), + CONSTRAINT uk_products_name_spec UNIQUE (product_name, spec_model) +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='产品表（类别锚定折算阈值参数；T+同步不覆盖产品类别）' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_products_source_no ON products (source_no); + +-- --------------------------------------------------------------------------- +-- 客户表（V4 迁移；公司名称+负责人为业务唯一标识，T+ 同步不覆盖客户分类） +-- --------------------------------------------------------------------------- +CREATE TABLE customers ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + company_name VARCHAR(128) NOT NULL COMMENT '公司名称', + owner_name VARCHAR(64) NOT NULL COMMENT '客户负责人姓名（客户公司负责人的人名，非系统人员）', + contact_person VARCHAR(64) COMMENT '联系人', + contact_phone VARCHAR(20) COMMENT '联系电话', + address VARCHAR(255) COMMENT '地址', + industry VARCHAR(64) COMMENT '所属行业（自由文本）', + customer_type VARCHAR(32) NOT NULL COMMENT '客户分类：personal个人户 manager_personal经理个人户 enterprise企业户（计提规则匹配锚点；T+同步不覆盖）' DEFAULT 'personal', + owner_personnel_id BIGINT UNSIGNED COMMENT '归属负责营销人员ID（手动修改不回溯历史，变更留痕见 ownership_change_logs）', + remark VARCHAR(255) COMMENT '备注', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + source_no VARCHAR(64) COMMENT 'T+ 原始单据号（同步幂等去重锚点；唯一键待 IT 定键后升级）', + t_plus_id VARCHAR(64) COMMENT 'T+ 系统内部标识', + sync_batch_no VARCHAR(32) COMMENT '同步批次号（同步模块写入）', + synced_at DATETIME COMMENT '最近同步时间', + CONSTRAINT pk_customers PRIMARY KEY (id), + CONSTRAINT uk_customers_company_owner UNIQUE (company_name, owner_name), + CONSTRAINT fk_customers_owner_personnel_id FOREIGN KEY(owner_personnel_id) REFERENCES personnel (id) ON DELETE RESTRICT +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='客户表（公司名称+负责人为业务唯一标识；T+同步不覆盖客户分类）' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_customers_customer_type ON customers (customer_type); + +CREATE INDEX idx_customers_owner_personnel_id ON customers (owner_personnel_id); + +CREATE INDEX idx_customers_source_no ON customers (source_no); + +-- --------------------------------------------------------------------------- +-- 归属变更记录表（V4 迁移，append-only；客户/业务归属变更留痕，不回溯历史） +-- --------------------------------------------------------------------------- +CREATE TABLE ownership_change_logs ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + owner_type TINYINT NOT NULL COMMENT '归属类型：1客户归属 2业务归属', + customer_id BIGINT UNSIGNED COMMENT '客户ID（固化，owner_type=1 时非空）', + business_id BIGINT UNSIGNED COMMENT '业务ID（固化，owner_type=2 时非空）', + old_owner_personnel_id BIGINT UNSIGNED COMMENT '变更前负责营销人员ID（固化）', + new_owner_personnel_id BIGINT UNSIGNED COMMENT '变更后负责营销人员ID（固化）', + old_assistant_personnel_id BIGINT UNSIGNED COMMENT '变更前协助营销人员ID（固化，仅业务归属使用）', + new_assistant_personnel_id BIGINT UNSIGNED COMMENT '变更后协助营销人员ID（固化，仅业务归属使用）', + change_reason VARCHAR(255) COMMENT '变更原因', + operator_id BIGINT UNSIGNED COMMENT '操作人ID（账号删除后置空）', + operator_name VARCHAR(64) NOT NULL COMMENT '操作人用户名（冗余固化）', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + CONSTRAINT pk_ownership_change_logs PRIMARY KEY (id), + CONSTRAINT fk_ownership_change_logs_operator_id FOREIGN KEY(operator_id) REFERENCES users (id) ON DELETE SET NULL +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='归属变更记录表（append-only；客户/业务归属变更留痕，不回溯历史）' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_ownership_change_logs_customer_id ON ownership_change_logs (customer_id); + +CREATE INDEX idx_ownership_change_logs_business_id ON ownership_change_logs (business_id); + +CREATE INDEX idx_ownership_change_logs_create_time ON ownership_change_logs (create_time); + -- --------------------------------------------------------------------------- -- 字典数据：角色（与 V1 迁移中的初始化数据一致） -- --------------------------------------------------------------------------- @@ -320,4 +467,4 @@ CREATE TABLE alembic_version ( CONSTRAINT alembic_version_pkc PRIMARY KEY (version_num) )CHARSET=utf8mb4 ENGINE=InnoDB COLLATE utf8mb4_general_ci; -INSERT INTO alembic_version (version_num) VALUES ('bfbda9c3191d'); +INSERT INTO alembic_version (version_num) VALUES ('e1133a7c670a'); diff --git a/db/migration/V4__add_base_data_tables.sql b/db/migration/V4__add_base_data_tables.sql new file mode 100644 index 0000000..6f501bc --- /dev/null +++ b/db/migration/V4__add_base_data_tables.sql @@ -0,0 +1,133 @@ +-- Running upgrade bfbda9c3191d -> e1133a7c670a + +CREATE TABLE products ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + product_name VARCHAR(128) NOT NULL COMMENT '产品名称', + spec_model VARCHAR(128) NOT NULL COMMENT '规格型号（空串而非 NULL：参与组合唯一键，MySQL 组合索引对 NULL 不去重）' DEFAULT '', + unit VARCHAR(16) COMMENT '计量单位', + stock_quantity NUMERIC(14, 2) COMMENT '数量（T+ 同步原样存储，语义待 IT 确认）', + sale_price NUMERIC(14, 4) COMMENT '销售单价（元，T+ 同步）', + product_category VARCHAR(32) NOT NULL COMMENT '产品类别：municipal_water市政水利 rail_transit轨道交通（决定折算阈值 30%/20%；T+同步不覆盖）', + status TINYINT NOT NULL COMMENT '状态：1启用 0停用' DEFAULT '1', + remark VARCHAR(255) COMMENT '备注', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + source_no VARCHAR(64) COMMENT 'T+ 原始单据号（同步幂等去重锚点；唯一键待 IT 定键后升级）', + t_plus_id VARCHAR(64) COMMENT 'T+ 系统内部标识', + sync_batch_no VARCHAR(32) COMMENT '同步批次号（同步模块写入）', + synced_at DATETIME COMMENT '最近同步时间', + CONSTRAINT pk_products PRIMARY KEY (id), + CONSTRAINT uk_products_name_spec UNIQUE (product_name, spec_model) +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='产品表（类别锚定折算阈值参数；T+同步不覆盖产品类别）' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_products_source_no ON products (source_no); + +CREATE TABLE ownership_change_logs ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + owner_type TINYINT NOT NULL COMMENT '归属类型：1客户归属 2业务归属', + customer_id BIGINT UNSIGNED COMMENT '客户ID（固化，owner_type=1 时非空）', + business_id BIGINT UNSIGNED COMMENT '业务ID（固化，owner_type=2 时非空）', + old_owner_personnel_id BIGINT UNSIGNED COMMENT '变更前负责营销人员ID（固化）', + new_owner_personnel_id BIGINT UNSIGNED COMMENT '变更后负责营销人员ID（固化）', + old_assistant_personnel_id BIGINT UNSIGNED COMMENT '变更前协助营销人员ID（固化，仅业务归属使用）', + new_assistant_personnel_id BIGINT UNSIGNED COMMENT '变更后协助营销人员ID（固化，仅业务归属使用）', + change_reason VARCHAR(255) COMMENT '变更原因', + operator_id BIGINT UNSIGNED COMMENT '操作人ID（账号删除后置空）', + operator_name VARCHAR(64) NOT NULL COMMENT '操作人用户名（冗余固化）', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + CONSTRAINT pk_ownership_change_logs PRIMARY KEY (id), + CONSTRAINT fk_ownership_change_logs_operator_id FOREIGN KEY(operator_id) REFERENCES users (id) ON DELETE SET NULL +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='归属变更记录表（append-only；客户/业务归属变更留痕，不回溯历史）' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_ownership_change_logs_customer_id ON ownership_change_logs (customer_id); + +CREATE INDEX idx_ownership_change_logs_business_id ON ownership_change_logs (business_id); + +CREATE INDEX idx_ownership_change_logs_create_time ON ownership_change_logs (create_time); + +CREATE TABLE personnel ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + personnel_name VARCHAR(64) NOT NULL COMMENT '姓名', + business_role_id BIGINT UNSIGNED NOT NULL COMMENT '岗位角色ID（决定计提公式模板；T+同步不覆盖）', + manager_id BIGINT UNSIGNED COMMENT '直属营销经理ID（NULL=经理本人或未分配；团队成员关系锚点）', + phone VARCHAR(20) COMMENT '联系电话', + hire_date DATE COMMENT '入职日期', + is_probation TINYINT NOT NULL COMMENT '是否试用期：1是 0否（试用期绩效照算不发放）' DEFAULT '0', + salary_standard NUMERIC(12, 2) COMMENT '月工资标准（元；T+同步不覆盖）', + status TINYINT NOT NULL COMMENT '状态：1在职 0离职（离职人员不可再被业务/客户归属引用）' DEFAULT '1', + remark VARCHAR(255) COMMENT '备注', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + source_no VARCHAR(64) COMMENT 'T+ 原始单据号（同步幂等去重锚点；唯一键待 IT 定键后升级）', + t_plus_id VARCHAR(64) COMMENT 'T+ 系统内部标识', + sync_batch_no VARCHAR(32) COMMENT '同步批次号（同步模块写入）', + synced_at DATETIME COMMENT '最近同步时间', + CONSTRAINT pk_personnel PRIMARY KEY (id), + CONSTRAINT fk_personnel_business_role_id FOREIGN KEY(business_role_id) REFERENCES business_roles (id) ON DELETE RESTRICT, + CONSTRAINT fk_personnel_manager_id FOREIGN KEY(manager_id) REFERENCES personnel (id) ON DELETE RESTRICT +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='营销人员表（T+同步不覆盖岗位与工资标准）' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_personnel_business_role_id ON personnel (business_role_id); + +CREATE INDEX idx_personnel_manager_id ON personnel (manager_id); + +CREATE INDEX idx_personnel_source_no ON personnel (source_no); + +CREATE TABLE customers ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + company_name VARCHAR(128) NOT NULL COMMENT '公司名称', + owner_name VARCHAR(64) NOT NULL COMMENT '客户负责人姓名（客户公司负责人的人名，非系统人员）', + contact_person VARCHAR(64) COMMENT '联系人', + contact_phone VARCHAR(20) COMMENT '联系电话', + address VARCHAR(255) COMMENT '地址', + industry VARCHAR(64) COMMENT '所属行业（自由文本）', + customer_type VARCHAR(32) NOT NULL COMMENT '客户分类：personal个人户 manager_personal经理个人户 enterprise企业户（计提规则匹配锚点；T+同步不覆盖）' DEFAULT 'personal', + owner_personnel_id BIGINT UNSIGNED COMMENT '归属负责营销人员ID（手动修改不回溯历史，变更留痕见 ownership_change_logs）', + remark VARCHAR(255) COMMENT '备注', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + source_no VARCHAR(64) COMMENT 'T+ 原始单据号（同步幂等去重锚点；唯一键待 IT 定键后升级）', + t_plus_id VARCHAR(64) COMMENT 'T+ 系统内部标识', + sync_batch_no VARCHAR(32) COMMENT '同步批次号（同步模块写入）', + synced_at DATETIME COMMENT '最近同步时间', + CONSTRAINT pk_customers PRIMARY KEY (id), + CONSTRAINT fk_customers_owner_personnel_id FOREIGN KEY(owner_personnel_id) REFERENCES personnel (id) ON DELETE RESTRICT, + CONSTRAINT uk_customers_company_owner UNIQUE (company_name, owner_name) +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='客户表（公司名称+负责人为业务唯一标识；T+同步不覆盖客户分类）' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_customers_customer_type ON customers (customer_type); + +CREATE INDEX idx_customers_owner_personnel_id ON customers (owner_personnel_id); + +CREATE INDEX idx_customers_source_no ON customers (source_no); + +CREATE TABLE personnel_plans ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + personnel_id BIGINT UNSIGNED NOT NULL COMMENT '人员ID（personnel.id）', + plan_period VARCHAR(32) NOT NULL COMMENT '计划期间（如 2026Q1、2026-05）', + plan_content VARCHAR(500) NOT NULL COMMENT '计划内容', + target_desc VARCHAR(255) COMMENT '指标说明（文字描述）', + source_no VARCHAR(64) COMMENT 'T+ 原始条目号（预留）', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + CONSTRAINT pk_personnel_plans PRIMARY KEY (id), + CONSTRAINT fk_personnel_plans_personnel_id FOREIGN KEY(personnel_id) REFERENCES personnel (id) ON DELETE RESTRICT +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='市场拓展计划表' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_personnel_plans_personnel_id ON personnel_plans (personnel_id); + +CREATE TABLE personnel_regions ( + id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT, + personnel_id BIGINT UNSIGNED NOT NULL COMMENT '人员ID（personnel.id）', + region_name VARCHAR(128) NOT NULL COMMENT '区域名称（产品辐射地理范围）', + remark VARCHAR(255) COMMENT '备注', + create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP, + update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + CONSTRAINT pk_personnel_regions PRIMARY KEY (id), + CONSTRAINT fk_personnel_regions_personnel_id FOREIGN KEY(personnel_id) REFERENCES personnel (id) ON DELETE RESTRICT +)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='产品辐射区域表' COLLATE utf8mb4_general_ci; + +CREATE INDEX idx_personnel_regions_personnel_id ON personnel_regions (personnel_id); + +UPDATE alembic_version SET version_num='e1133a7c670a' WHERE alembic_version.version_num = 'bfbda9c3191d'; + diff --git a/db/queries/基础数据.sql b/db/queries/基础数据.sql new file mode 100644 index 0000000..aa38ff5 --- /dev/null +++ b/db/queries/基础数据.sql @@ -0,0 +1,98 @@ +-- ============================================================================ +-- 基础数据查询留档（M2 基础数据管理） +-- +-- 设计要点： +-- - 人员团队关系用 manager_id 自引用展开（NULL=经理本人或未分配）， +-- M3 经理 12.5% 聚合与 M4 部门汇总均按此关系，无独立团队表 +-- - 归属变更留痕（ownership_change_logs）对客户/业务/人员 ID 为无外键的 +-- 冗余固化：被引用方删除后记录仍须完整可读，join 不到时以固化值为准 +-- - T+ 预留列（source_no 等）当前全部为空，同步模块（M4）上线后启用 +-- ============================================================================ + +-- 1. 人员列表（含岗位名称与直属经理姓名；分页 + 关键字筛选） +SELECT p.id, + p.personnel_name, + p.phone, + p.hire_date, + p.is_probation, + p.salary_standard, + p.status, + br.role_name, + br.role_code, + m.personnel_name AS manager_name +FROM personnel p +JOIN business_roles br ON br.id = p.business_role_id +LEFT JOIN personnel m ON m.id = p.manager_id +WHERE (:keyword IS NULL OR p.personnel_name LIKE CONCAT('%', :keyword, '%')) + AND (:status IS NULL OR p.status = :status) +ORDER BY p.id DESC +LIMIT :limit OFFSET :offset; + +-- 2. 某经理的团队成员（M3 经理 12.5% 聚合的取数口径） +SELECT p.id, p.personnel_name, p.business_role_id, p.status +FROM personnel p +WHERE p.manager_id = :manager_id + AND p.status = 1; + +-- 3. 人员的辐射区域与拓展计划（编辑抽屉回显，随人员整表替换维护） +SELECT region_name, remark +FROM personnel_regions +WHERE personnel_id = :personnel_id +ORDER BY id; + +SELECT plan_period, plan_content, target_desc, source_no +FROM personnel_plans +WHERE personnel_id = :personnel_id +ORDER BY id; + +-- 4. 产品目录（名称/规格关键字 + 类别筛选；名称+规格为组合唯一键） +SELECT id, product_name, spec_model, unit, stock_quantity, sale_price, + product_category, status +FROM products +WHERE (:keyword IS NULL OR product_name LIKE CONCAT('%', :keyword, '%') + OR spec_model LIKE CONCAT('%', :keyword, '%')) + AND (:product_category IS NULL OR product_category = :product_category) + AND (:status IS NULL OR status = :status) +ORDER BY id DESC +LIMIT :limit OFFSET :offset; + +-- 5. 客户列表（公司/负责人关键字 + 分类 + 归属人员筛选） +SELECT c.id, c.company_name, c.owner_name, c.customer_type, c.status, c.owner_personnel_id, + p.personnel_name AS owner_personnel_name +FROM customers c +LEFT JOIN personnel p ON p.id = c.owner_personnel_id +WHERE (:keyword IS NULL OR c.company_name LIKE CONCAT('%', :keyword, '%') + OR c.owner_name LIKE CONCAT('%', :keyword, '%')) + AND (:customer_type IS NULL OR c.customer_type = :customer_type) + AND (:owner_personnel_id IS NULL OR c.owner_personnel_id = :owner_personnel_id) +ORDER BY c.id DESC +LIMIT :limit OFFSET :offset; + +-- 6. 归属变更留痕（客户或业务维度；join 人员出姓名，人员已删时显示固化 ID） +SELECT l.id, + l.owner_type, + l.customer_id, + l.business_id, + l.old_owner_personnel_id, + l.new_owner_personnel_id, + po.personnel_name AS old_owner_name, + pn.personnel_name AS new_owner_name, + l.change_reason, + l.operator_name, + l.create_time +FROM ownership_change_logs l +LEFT JOIN personnel po ON po.id = l.old_owner_personnel_id +LEFT JOIN personnel pn ON pn.id = l.new_owner_personnel_id +WHERE (:customer_id IS NULL OR l.customer_id = :customer_id) + AND (:business_id IS NULL OR l.business_id = :business_id) +ORDER BY l.create_time DESC, l.id DESC +LIMIT :limit OFFSET :offset; + +-- 7. 归属变更留痕（幂等校验辅助：人员删除保护——被归属引用者不可物理删除） +SELECT COUNT(*) AS ref_count +FROM customers c +WHERE c.owner_personnel_id = :personnel_id +UNION ALL +SELECT COUNT(*) +FROM personnel m +WHERE m.manager_id = :personnel_id; diff --git a/docs/项目阶段报告_2026-10-13.md b/docs/项目阶段报告_2026-10-13.md new file mode 100644 index 0000000..16f459b --- /dev/null +++ b/docs/项目阶段报告_2026-10-13.md @@ -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)